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CHAPTER 1 
Introduction 


Always make a back-up _ 

Before using DevpacST you should make a back-up copy of the 
distribution disk and put the original away In a safe place. It Is not 
copy-protcctcd to allow easy back-up and to avoid Inconvenience. 
This disk may be backed-up using the Desktop or any back-up 
utility. The disk Is single-sided but may be used In double-sided 
drives. 

Before hiding away your master disk make a note in the bpx'toelov 
of the serial number written on It. You will need to qiiMfe 1 : JWd. 

require technical support. 


Serial No: 


Registration Card _ 

Enclosed with this manual Is a registration card which you should 
fill in and return to us after reading the licence statement. Without 
it you will not be enUtled to technical support or upgrades. Be sure 
to nil in all the details especially the serial number and version 
number. Also supplied Is a 68000 Pocket Guide which details the 
entire 68000 instruction set. 

The README File_ 


As with all HiSoh products DevpacST is continually being improved 
and the latest details that cannot be included in this manual may 
be found In the readme . S Me on the disk. This Me should be read at 
this point, by double-clicking on its icon from the Desktop and 
then clicking on the Show button. You can direct it to a printer by 
clicking on the Print button. 
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The Development Cycle 


The purpose of DevpacST is to allow you to enter assembly 
language programs, assemble them to machine-code and debug 
them if (or should that be when! they don't work. Depending on 
your application, you may also be using a linker to j&ta together 
separate modules, possibly with the output froi» & kigh level 
language compiler. Of course the faster the devctopwralpcle. the 
faster you can get your programs up and running wfevpacST 
was designed to be as fast and powerful as possible] Tire usual 
development cycle Is best illustrated by a diagram. 



Of course the faster the cycle, the faster you can get your 
programs up and running and DevpacST was designed to be as 
fast and powerful as possible. The Link stage is optional, as is the 
Compile stage. 
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DevpacST Disk Contents 


The supplied single-sided 3.5" disk contains these flics: 


Programs 


GENST2.PRG 
M0NST2.PRG 
MONST2..X0S 
GENSiSSs*#®* 

CHECKS 
linkS¥;‘M ' 
NOTRACE.PRG 
MENU2ASM.TTP 


GEM screen editor and assembler 
the GEM program debugger 
the TOS program debugger 
stand-alone version of assembler 
auto-resident debugger 
diagnostic program 
GST-format linker 
trace exception dis-abler 
menu compiler 


Text Files 


README.S 
DEMO.S 
GEMTEST.S 
DESKACC.S 
GEMMACRO.S 
AESLIB.S 
VDILIB.S 
NOTRACE.S 
MENUTEST.S 
MENUTEST.MDF 
MAKEGEM.S 
GEMLIB.LNK 


latest details about DevpacST 

very simple TOS program used in tutorial 

simple GEM demo program 

example desk accessory 

macros for AES/VDI interface 

AES library source 

VD1 library source 

source to notrace . prg 

example GEM program using menu 

sample menu definition flic 

creates GEMLIB 

control file for GEMLIB 


Binary Files 

GEMLIB.BIN AES & VDI library 

Folders 

OLDGEM updated GEM examples from GenST 1 
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How to Use this Mafe gi_ 

This manual makes no attempt to teach 68000 assembly language 
programming or to detail the Instruction set. For the former, the 
bibliography lists suitable books, while for the latter the supplied 
Pocket Guide is very useful. The Appendices give an overview of the 
technical aspects of the Atari ST but they are not Intended as a 
complete technical description of the machine. 

This manual Is set out in five chapters, this introduction, a chapter 
on the screen editor, a chapter on the macro assembler, a chapter 
on the debugger, then a chapter on the linker. In addition there arc 
eight Appendices which detail various additional Information. We ^ 
suggest you use the manual in a way that depends on what type of 
user you arc: 

DevpacST Version 1 Users _ 


Turn to Appendix H and read the section describing the new 
features, then read the Reference section of Chapter 4 If you 
intend using MonST, as it has changed considerably. The other 
section you may need to read is that on File Formats in Chapter 3 if 
you arc Interested in generating linkable code. 

Beginners _ 


If you are a newcomer to assembly language then we recommend 
that you read one of the books in the Bibliography alongside this 
manual. 

At the end of this chapter there is a simple tutorial which you 
should follow to familiarise yourself with the use of the main parts 
of the program suite. 

Chapter 2 details the editor and is well worth reading, though 
much of Chapter 3, detailing the assembler, is liable to mean 
nothing until you become more experienced. The Overview section 
of Chapter 4, the debugger, is strongly recommended, though 
Chapter 5 and the Appendices can be left for a while. Looking at 
the supplied source code may be helpful, but the GEM programs 
may be hard going as they were not written with the beginner in 
mind. 
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Experienced Users 


If you are experienced in the use of 68000 assembly language but 
have not used DevpacST before then here Is a very quick way of 
assembling a source file: 

Load GENST2. prg. Press Alt-L and select your file which will load 
into the editor. Press Alt -a and select the options which you 
require - if generating executable code then click on the Memory 
button for additional speed. Pressing Return will start the 
bi'flSKmbler, which may be paused by pressing ctri-S, ctrl-Q 
^Spines. Jfeiy lisfe'embly errors will be remember and on return to 
ffiwSflStar you will be placed on the first one. Subsequent errors 
m.'SfW^foimd % pressing Alt- j. 

ICo riaffi TOiffi' ®4:^sessfully-assembled program (if assembled to 
S&emo.yf pres*? If assembled to disk press Ait-o then select 

program. 

& quadv Introduction to the debugger the following tutorial is 
w.nanmended. If you have any problems please read the relevant 
secttan of the manual before contacting us for technical support. 

A Very Quick Tutorial _ 

This is a quick tutorial intended to let you see how quick and easy 
it is to edit, assemble and debug programs with DeUpacSfi 

In this tutorial we are going to assemble and run a simple program, 
which contains two errors, and debug it. The program itself is 
intended to print a message m& wait for a key to be pressed before 
quitting. 

To start with load GENST2 ,W!B from your backup copy (you have 
made a backup, haven't you?) which must also contain the files 
MONST2.PRG and demo.s, at minimum, by double-clicking on its 
icon. After a short delay the screen will show an empty window; to 
load the file you should move the mouse over the File menu and 
click on Load. The standard GEM file selector will then appear and 
the file we want is called demo.S. You may either double-cUck on the 
name or type it in and press Return to load the file. 

When the file has loaded the window will show the top lines of the 
file. If you want to have a quick look at the program you may click 
on the scroll bar or use the cursor keys. 
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With most shorter programs it is best to have a trial assembly that 
doesn't produce a listing or binary file to check the syntax of the 
source and show up typing errors and so on. Move the mouse to 
the Program menu and click on Assemble. 

A dialog box will appear, which should be left alone except the 
button near the bottom, labelled None, should be clicked on. Click 
on the Assemble button or press Return and the assembly will 
begin. 

The assembler will report an error, instruction not recognised, 
and pressing any key will return you to the editor. The cursor will 
be placed on the incorrect line and the error message displayed in , 
the status line. W' 

The program line should be changed from mov.w to move.w, so do 
this, then click on Assemble from the Program menu again. This 
time click on the Memory button, this means the program will be 
assembled into memory, instead of onto disk. This is very much 
faster and allows you to try things out immediately, which is 
exactly what we want. Clicking on the Assemble button will again 
assemble it. and after you press a key to return to the editor it’s 
ready to run. 

The assembly worked this time, so click on Run from the Program 
menu, and what happens? Not a lot It would seem, except that a 
.CQMjjte of bombs appeared briefly on the screen - oh. there's a bug. 

Tlys tool for finding bugs is a debugger, so click on Debug from the 
f-TCJgram menu. The debugger is described more fully later on. but 
f<*f r.aw we Just want to run the program from the debugger to 
’catch" the bombs and find out what causes them, so press ctri-R. 

After a brief delay the message Bus Error will appear in the bottom 
window, with the disassembly window showing the current j 
instruction ''*** 

MOVE.W 1,-<A7) 

This will cause a bus error because location 1 is in protected 
memory which cannot be accessed in user mode - there should a 
hash sign before the 1 to put the immediate value of 1 on the stack. 

To return to the editor press ctrl-c. so we can fix this bug in the 
source code. 
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Press Alt-T, to go to the top of the file, then click on Find from the 
Search menu. We are going to find the errant Instruction so enter 


then press Return to start the search. The first occurrence has a 
hash sign, so press Alt-N to find the next which is the line 

move.w c_conin,- (a7) 

Ahahl - this is the one, so add a hash to change it to 
^ ^ move.w lc_conin,-(a7) 

then assemble It again. If you click on Run from the Program menu 
you should see the message, and pressing any key will return you 
to the editor. 

However, did you notice how messy the screen was - the desktop 
pattern looked very untidy and you possibly got mouse 
'droppings' left on the screen. This was because demo Is a TOS 
program running with a GEM screen - to change this, click on Run 
with GEM from the Program menu - the check mark next to It 
should disappear. If you select Run again you can see the display Is 
a lot neater. Isn't It? If you run a GEM program you must ensure 
the check mark Is there beforehand, otherwise nasty things can 
happen. 

Although the program now works we shall use MonST. the 
debugger, to trace through the program, step by step. To do this 
click on Debug from the Program menu, and the debugger will 
appear with the message Breakpoint, showing your program. 

There are various windows, the top one displaying the machine 
registers, the second a disassembly of the program, the third 
W some other memory, and the bottom window displaying various 
messages. 

If you look at window 2. the disassembly window, you will see the 
current Instruction, which In our case Is 

MOVE.L fstring,-<A7) 

As the debug option was specified In the source code any symbols 
will appear In the debugger. 
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Let's check the area around string. Press Alt-3 and you should 
see window 3's title Inverted. Next press Alt-A and a dialog box will 
appear, asking Window start address? - to this enter 

string 

(It must be in lower-case) and press Return. This will re-dlsplay 
window 3 at that address, showing the message in both hex and 
ASCII. 

To execute this JKjVK Instruction press ctrl-z. This will execute the 
instruction feiEti the screen will be updated to reflect the new 
values of the pstigvam counter and register A7. If you press ctrl-z 
again the move . W instruction will be executed. If you look at the hex 
display next to A7 you should see a word of 9. which Is what you 
would expect after that Instruction. 

The next instruction Is trap ii, to call GEMDOS to print a string, 
but hang on - would we notice a string printed In the middle of the 
MonST display? Never fear. MonST has Its own screen to avoid 
interference with your program's, to see this press the v key. 
which will show a blank screen, ready for your program. Pressing 
any other key will return you to MonST. 

To execute this call press Ctrl-z. which will have printed the 
string. To prove it press v again, then any key to return to MonST. 

Press Ctrl-z twice more until you reach the next Trap. This one 
waits for a key press so hit Ctrl-z and the program display will 
automatically appear, waiting for a key. When you're ready, press 
the q key. You will return to MonST and If you look at the register 
window the low 8 bits of register do should be $71, the ASCII code 
for q, and next to that it will be shown as q (unless In low- 
resolution). 

The final Trap quits the program, so to let it run Its course press 
Ctn-R, you will then return to the editor as the program has 
finished. 

Note the way we have used the courier font to indicate text or 
values that appear on screen or Input to be typed from the 
keyboard. Also, ctrl-x means hold the Ctrl key down on the 
keyboard and press x. while Return Indicates that you should 
press the Return key on the keyboard. These conventions will be 
used throughout the manual. 
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CHAPTER 2 
Screen Editor 




Introduction 


To enter and assemble your programs you need an editor of some 
sort and an assembler. GenST combines both of these functions 
together In one Integrated program, giving a GEM-drlven full¬ 
screen editor and a fast, full-speclflcatlon assembler. It also allows 
you to run your assembled programs directly from memory 
without having to quit the program or do a disk access and to 
access the debugger at the press of a key. The fact that all these 
features are combined In one program means that correcting 
errors and making changes Is as fast as possible without the need 
for slow disk accesses and other pnsifraak. 

This chapter details the use of th® cdto and how to assemble 
programs - it does not detail the assembler or the debugger 
themselves, they are covered in the following chapters. 




To run GenST. double click on the genst2.prg icon from the 
Desktop. When it has loaded a menu bar will appear and an empty 
window will open, ready for you to enter and assemble your 
programs. 


The Editor 


A text editor Is a program which allows you to enter and alter lines 
of text, store them on disk, and load them back again. There are 
two types of text editors: line editors, which treat each line 
separately and can be very tricky to use. and screen editors, which 
display your text a screen at a time. The latter tend to be much 
easier to use. 
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The editor section of GenST Is a screen editor which allows you to 
enter and edit text and save and load from disk, as you would 
expect. It also lets you print some or all of your text, search and 
replace text patterns and use any of the STs desk-accessories. It Is 
GEM-based, which means It uses all the user-friendly features of 
GEM programs that you have become familiar with on your 
computer such as windows, menus and mice. However, If you're a 
die-hard, used to the hostile world of computers before the advent 
of WIMPs, you'll be pleased to know you can do practically 
everything you'll want to do from the keyboard without having to 
touch a mouse. 

The editor Is 'RAM-based', which means that the file you are 
editing stays In memory for the whole time, so you don't have to 
wait while your disk grinds away loading different sections of the 
file as you edit. As the ST range has so much memory, the size 
limitations often found In older computer editors don't exist with 
GenST; If you have enough memory you can edit flies of over 300k 
(though make sure your disk Is large enough to cope with saving It 
If you dot). As all editing operations. Including things like 
searching, are RAM-based they act blindingly quickly. 

When you have typed In your program it Is not much use If you are 
unable to save It to disk, so the editor has a comprehensive range of 
save and load options, allowing you to save all or part of the text 
and to load other files Into the middle of the current one, for 
example. 

To get things to happen In the editor, there are various methods 
available to you. Features may be accessed In one or more of the 
following ways; 

• Using a single key, such as a Function or cursor key; 

• Clicking on a menu item, such as Save; 

• Using a menu shortcut, by pressing the Alternate key 
(subsequently referred to as Alt) In conjunction with 
another, such as Alt-F for Find; 

• Using the Control key (subsequently referred to as Ctrl) In 
conjunction with another, such as ctrl-A for cursor word 
left: 


Clicking on the screen, such as In a scroll bar. 
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The menu shortcuts have been chosen to be easy and obvious to 
remember, while the Ctrl commands are based on those used In 
WordStar, and many other compatible editors since. 

If at any time you get stuck, pressing the Help key will bring up a 
comprehensive display of the keys required for functions not 
visible in any menus. 

A Few Words about Dialog Boxes _ 

The editor makes extensive use of Dialog boxes, so it is worth 
recapping how to use them, particularly for entering text. The 
editor's dialog boxes contain buttons, radio buttons, and editable 
text. 


Buttons may be clicked on with the mouse and cause the dialog box 
to go away. Usually there Is a default button, shown by having a 
wider border than the others. Pressing Return on the keyboard Is 
equivalent to clicking on the default button. 

Radio buttons are groups of buttons of which only one may be 
selected at a time - clicking on one automatically de-selects all the 
others. 

Editable text is shown with a dotted line, and a vertical bar marks 
the cursor position. Characters may be typed In and corrected 
using the Backspace, Delete and cursor keys. You can clear the 
whole edit field by pressing the Esc key. If there Is more than one 
editable text field In a dialog box. you can move between them using 
the 1 and T keys or by clicking near them with the mouse. 

Some dialog boxes allow only a limited range of characters to be 
typed Into them - for example the Goto Line dialog box only allows 
numeric characters (digits! to be entered. 

Entering text and Moving the cursor 

Having loaded GenST, you will be presented with an empty window 
with a status line at the top and a flashing black block, which Is the 
cursor. In the top left-hand comer. 
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The status line contains information about the cursor position in 
the form of line and Column offsets as well as the number of bytes 
of memory which are free to store your text. Initially this is 
displayed as 59980. as the default text size is 60000 bytes. You 
may change this default if you wish, together with various other 
options, by selecting Preferences, described later. The 'missing' 20 
bytes are used by the editor for internal information. The rest of 
the status line area is used for error messages, which will usually 
be accompanied by a 'ping' noise to alert you. Any message that 
gets printed will be removed subsequently when you press a key. 

To enter text, you type on the keyboard. As you press a key it will 
be shown on the screen and the cursor will be advanced along the 
line. If you are a very good typist you may be able to type faster 
than the editor can re-display the line; if so. don't worry, as the 
program will not lose the keystrokes and will catch up when you 
pause. At the end of each line vor press the Return key (or the 
Enter key on the numeric pao) to start the next line. You can 
correct your mistakes by pressing the Backspace key. which 
deletes the character to the left of the cursor, or the Delete key. 
which removes the character the cursor is over. 

The main advantage of a computer editor as opposed to a normal 
typewriter is its ability to edit things you typed a long time ago. 
The editor's large range of options allow complete freedom to move 
around your text at will. 

Cursor keys _ 


To move the cursor around the text to correct errors or enter new 
characters, you use the cursor keys, labelled «- -* t and i. If you 
move the cursor past the right-hand end of the line this won't add 
anything to your text, but ifyou try to type some text at that point 
the editor will automatically add the text to the real end of the line. 
If you type in long lines the window display will scroll sideways if 
necessary. 

If you cursor up at the top of a window the display will either scroll 
down If there is a previous line, or print the message Top of file 
in the status line. Similarly if you cursor down off the bottom of the 
window the display will either scroll up If there is a following line, or 
print the message End of file. 

You can move the cursor on a character basis by clicking on the 
arrow boxes at the end of the horizontal and vertical scroll bars. 
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For those of you used to WordStar, the keys ctrl-S, ctrl-D, Ctrl- 
e and ctrl-x work in the same way as the cursor keys. 


To move Immediately to the start of the current line, press Ctrl 
and to move to the end of the current line press Ctrl 

To move the cursor a word to the left, press shift«- and to move a 
word to the right press shift You cannot move past the end of a 
line with Shift A word is defined as anything awnmndtsi 5jy.a 
space, a tab or a start or end of line. The keys Ct rl'-A 

also move the cursor left and right on a word basis. 

To move the cursor a page up. you can click on the kjpsjsff 
of the vertical scroll bar. or press ctri-R or ShifT» tawe-TO8 
cursor a page down, you can click on the lower gby'parti«■'tiae 
scroll bar. or press ctrl-c or shift i. 




If you want to move the cursor to a specific position on the screen 
you may move the mouse pointer to the required place and click 
(There is no WordStar equivalent for this feature!). 


Tab key 


The Tab key Inserts a special character (ASCII code 9) into your 
text, which on the screen looks like a number of spaces, but is 
rather different. Pressing Tab aligns the cursor onto the next 
multiple of 8‘ column, so if you press it at the start of a line 
(column 1) the cursor moves to the next multiple of 8. +1, which is 
column 9. Tabs are very useful indeed for making items line up 
vertically and its main use in GenST is for making instructions line 
up. When you delete a tab the line closes up as if a number of spaces 
had been removed. The advantage of tabs is that they take up only 
1 byte of memory, but can show on screen as many more, allowing 
you to tabulate your program neatly. You can change the tab size 
before or after loading GenST using the Preferences command 
described shortly. 
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Backspace key 


The Backspace key removes the character to the left of the cursor. 
If you backspace at the very beginning of a line it will remove the 
'invisible' carriage return and Join the line to the end of the previous 
line. Backspacing when the cursor is past the end of the line will 
delete the last character on the line, unless the line is empty in 
which case it will re-position the cursor on the left of the screen. 

Delete key _ 


The Delete key removes the character under the cursor and has 
no effect if the cursor is past the end of the current line. 

Goto a particular line _ 


To move the cursor to a specific line in the text, click on Goto line... 
from the Options menu, or press Alt-G. A dialog box will appear, 
allowing you to enter the required line number. Press Return or 
click in the OK button to go to the line or click on Cancel to abort 
the operation. After clicking on OK the cursor will move to the 
specified line, re-displaying if necessary, or give the error End of 
file if the line doesn't exist. 

Another fast way of moving around the file is by dragging the 
slider on the vertical scroll bar, which works in the usual GEM-llke 
fashion. 

Go to top of file _ 


To move to the top of the text, click on Goto Top from the Options 
menu, or press Alt-T. The screen will be re-drawn if required 
starting from line 1. 

Go to end of file 


To move the cursor to the start of the very last line of the text, click 
on Goto Bottom, or press Ait-B. 
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Quitting GenST 


To leave GenST, click on Quit from the File menu, or press Alt-Q. If 
changes have been made to the text which have not been saved to 
disk, an alert box will appear asking for confirmation. Clicking on 
Cancel will return you to the editor, while clicking on OK will 
discard the changes and return you to the Desktop. 

Deleting text _ 

Delete line ___ 

The current line can bi? dieted from the text by pressing Ctrl-Y. 

Delete to end gil Jpie _ 

The text from the cursor position to the end of the current line can 
be deleted by pressing ctrl-Q. (This Is equivalent to the WordStar 
sequence ctrl-Q y). 

UnDelete Line __ 

When a line Is deleted using either of the above commands It Is 
preserved in an Internal buffer, and can be re-lnserted into the text 
by pressing ctrl-o, or the undo key. This can be done as many 
times as required, particularly useful for repeating similar lines or 
swapping over Individual lines. 

Delete all the text _ 

To clear out the current text, click on Clear from the File menu, or 
press Alt-C. If you have made any changes to the text that have 
not been saved onto disk, a confirmation is required and the 
requisite alert box will appear. Clicking on OK will delete the text, or 
Cancel will abort the operation. 
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Disk Operations 


It Is no use being able to type in text If you are unable to save it 
anywhere permanently, or load it back subsequently, so the editor 
has a comprehensive set of features to read from and write to disk. 

GEM File Selector_ 


Before describing the commands, it is best to detail the GEM File 
Selector, which is a consistent way for users to select filenames 
from disk. It is the same in all programs, so if you have used it 
before then you can skip to the next section. 

Figure 2.1 shows an example of the file selector box. At the top the 
current drive, directory and type selection is shown. To the right is 
a space for the actual filename, with OK and Cancel buttons below 
it and a window taking up most of the remainder of the selector. 
This window displays all of the filenames that correspond to the 
drive and directory above. 





Figure 2.1 - the GEM File Selector 
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To select a filename, to save or to load, you can either click on the 
name shown In the window, perhaps after using the scroll bar to 
go up or down the list, or type It In at the Selection area. If you click 
on a filename it will automatically be copied into the Selection area. 
Clicking on OK or pressing Return wffi choose that particular 
filename, or once you get used to the wdedsSr you may double-click 
on the filename, obviating the new) ft dick on OK or to press 
Return. 

If the file you want is not in the sub-directory shown, you can go 
i down a directory level by clicking on the directory name In the 
window, or you can go up a directory by clicking on the close box of 
the filename window. By default. GenST displays all files ending In 
. s. as this is the usual extension for assembly language programs. 
If you want to change this, you have to edit the Directory string 
and replace the . s with the extension of you choice, such as . asm. If 
you want to be shown all the files, regardless of extension, replace 
the .s with . *. If you do edit the Directory string you need to click 
In the filename area of the window to tell GEM to re-display the 
filenames. If you want to change the disk drive specifier, you 
should click on the Directory string with the mouse (or press T ). 
edit it to suit and click in the filename area of the window. 


11130 In all pre-blitter versions of the ST ROMs there Is a bug 
which means that If you press _ (underline) when the cursor Is in 
the Directory string the machine will crash! 


Saving Text 




To save the text you are currently etMtif&tg, didS'On Save As from 
the File menu, or press Ait-s. The GSM File Selector will 

appear, allowing you to select a sultsfofe filename. Clicking 

OK or pressing Return will then s„«» the SJe twtto the disk. If an 
error occurs a dialog will appear shtjwfcg .aTO® orror number, the 
exact meaning of which can be found in Appendix A. 


If you click on Cancel the text will not be saved. Normally If a file 
exists with the same name it will be deleted and replaced with the 
new version, but if Backups are selected from the Preferences 
options then any existing file will be renamed with the extension 
.bak (deleting any existing .bak file) before the new version is 
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If you have already done a Save As (or a load), GenST will 
remember the name of the file and display it in the title bar of the 
window. If you want to save it without having to bother with the file 
selector, you can click on Save on the File menu, or press shift- 
Alt-S. and it will use the old name and save it as above. If you try to 
Save without having previously specified a filename you will be 
presented with the File Selector, as in Save As. 

Loading Text _ 


To load in a new text file, click on Load from the File menu, or press 
Alt-L. If you have made any changes that have not been saved, a 
confirmation will be required. The GEM file selector will appear, 
allowing you to specify the disk and filename. Assuming you do not 
Cancel, the editor will attempt to load the file. If It will fit. the file is 
loaded into memory and the window is re-drawn. If it will not fit an 
alert box will appear warning you. and you should use Preferences 
to make the edit buffer size larger, then try to load it again. 

Inserting Text _ 

If you want to read a file from disk and insert it at the current 
position in your text click on Insert File from the File menu, or press 
Alt-i. The standard GEM file selector will appear and assuming 
that you do not cancel, the file will be read from the disk and 
inserted, memory permitting. 
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Searching and Replacing Text 


To find a particular section of text click on Find from the Search 
menu, or press Ait-F. A dialog box will appear, allowing you to 
enter the Find and Replace strings. If you click on Cancel, no 
action will be taken; If you click Next (or press Return) the search 
wlU start forwards, while cUcklng on Previous will start the search 
backwards. If you do not wish to replace, leave the Replace string 
empty. If the search was successful, the screen will be re-drawn at 
t, that point with the cursor positioned at the start of the string. If 
the search string could not be found, the message Not found will 
appear In the status area and the cursor will remain unmoved. By 
default the search Is always case-independent, so for example if 
you enter the search string as test you could find the words test, 
Test and test. If you click on the UPPER & lower case Different 
button the search will be case-dependent. 

To find the next occurrence of the string click on Find Next from the 
Search menu, or press Ait-N. The search starts at the position 
Just past the cursor. 

To search for the previous occurrence of the string click on Find 
Previous from the Search menu, or press Alt-P. The search starts 
at the position just before the cursor. 

Having found an occurrence of the required text. It can be replaced 
with the Replace string by clicking on Replace from the Search 
menu, or by pressing Alt-R. Having replaced It. the editor will then 
search fer the next occurrence. 

ff you. wfch to replace every occurrence of the And string with the 
'w replace string (mm the cursor position onwards, click on Replace 
Ail from the Search menu. During the global replace the Esc key 
east be used to abort and the status area will show how many 
replacements mi® made. There Is deliberately no keyboard 
equivalent for this to prevent it being chosen accidentally. 

Block Commands_ 


A block is a marked section of text which may be copied to another 
section, deleted, printed or saved onto disk. The function keys are 
used to control blocks. 
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Marking a block _ 

The start of a block Is marked by moving the cursor to the required 
place and pressing key Fl. The end of a block Is marked by moving 
the cursor and pressing key F2. The start and end of a block do not 
have to be marked In a specific order - if it Is more convenient you 
may mark the end of the block first. 

A marked block is highlighted by showing the text in reverse. While 
you are editing a line that is within a block this highlighting will 
not be shown but will be re-displayed when you leave that line or 
choose a command. 

Saving a block _ 

Once a block has been marked, it can be saved by pressing key F3. If 
no block Is marked, the message What blocks! will appear. If the 
start of the block is textually after its end the message invalid 
block! will appear. Both errors abort the command. Assuming a 
valid block has been marked, the standard GEM file selector will 
appear, allowing you to select a suitable disk and filename. If you 
save the block with a name that already exists the old version will 
be overwritten - no backups are made with this command. 

Copying a block _ •_ 


A marked block may be copied, memory permittQ!^ taS; another 
part of the text by moving the cursor to where you want the block 
copied and pressing key F4. If you try to copy a block Into a part of 
itself, the message invalid block will appear and the copy will be 
aborted. 

Deleting a block _ 


A marked block may be deleted from the text by pressing 'SXtxirSS. 
The shift key is deliberately required to prevent ftJfasteg 
accidentally. A deleted block is remembered, memoijr petiwfttfeig. 
In the block buffer, for later use. 


This is on a different key to that used in GenST in 
versions before 2.0. 
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Copy block to block buffer 


<w 


The current marked block may be copied to the block buffer, 
memory permitting, by pressing sbift-F4. This can be very useful 
for moving blocks of text between different flies by loading the first, 
marking a block, copying it to the block buffer then loading the 
other file and pasting the block buffer Into It. 

Pasting a block _ 

A block in the block buffer may be pasted at the current cursor 
position by pressing F5. 




The block buffer will be lost if the edit buffer size Is 
changed or an assembly occurs. 


Printing a block _ 

A marked block may be sent to the printer by clicking on Print Block 
from the File menu, or by pressing Ait-w. An alert box will appear 
confirming the operation and clicking on OK will print the block. 
The printer port used will depend on the port chosen with the 
Install Printer desk accessory, or will default to the parallel port. 
Tab characters are sent to the printer as a suitable number of 
spaces, so the net result will normally look better than If you print 
the file from the Desktop. 

If you try to Print whswrao block is marked at all then the whole file 
^ will be printed. 


Block markers remain during all editing commands, moving where 
necessary, and are only reset by the commands New. Delete 
block, and Load. 
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Miscellaneous Commands 


About GenST2 


It you click on About GenST2... from the Desk menu, a dialog box 
will appear giving various details about GenST Pressing Return or 
clicking on OK will return you to the editor. 

Help Screen . . . 


The key equivalents for the commands not found in menus can be 
seen by pressing the Help key. or Alt-H. A dialog box will appear 
showing the WordStar and function keys, as well as the free 
memory left for the system. 

Preferences 


Selecting Preferences... from the Options menu wrtH produce « 
dialog box allowing you to change several editor settings: 

Tabs_ 


By default, the tab setting is 8. but this may be changed to any 
value from 2 to 16. 

Text Buffer Size _ 


By default the text buffer size is 60000 bytes, but this can be 
changed from 4000 to 999000 bytes. This determines the largest , 
file size that can be loaded and edited. Care should be taken to leave 
sufficient room in memory for assembly or running MonST - 
pressing the Help key displays free system memory, and for 
assembly or debugging this should always be at least 100k bytes. 
Changing the editor workspace size will cause any text you are 
currently editing to be lost, so a confirmation is required if it has 
not been saved. 
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Numeric Pad 


The Numeric Pad option allows the use of the numeric keypad In 
an IBM-PC-llke way allowing single key presses for cursor 
functions, and defaults to Cursor pad mode. The keypad works as 
shown in Figure 2.2 below. 
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Figure 2.2 Numeric Keypad 

This feature can be disabled. If required, by clicking on the Numbers 
button. 

Backups _ 

By default the editor does not make backups of programs when 
you save them, but this can be turned on by clicking on the Yes 
radio button. 

Auto Indenting ___ 

It can be particularly useful when editing programs to Indent 
subsequent lines from the left, so the editor supports an auto- 
lndent mode. When active, an Indent Is added to the start of each 
new line created when you press Return. The contents of the 
Indent of the new line Is taken from the white space (l.e. tabs 
and/or spaces) at the start of the previous line. 

Cursor __ 

By default the GenST cursor flashes but this can be disabled If 
required. 
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B,j SfefessK jR. copy of MonST is loaded during the editor 
MfcifflUsatisesi, sBcwriog It to-be accessed at the press of a key. Should 
this not be Wtjiyitd disabled with this option. This will 

«3 ssro and S4fe of K^rnsy-,-. The new value of this option will only 
Mv«.m^teiiTyofci s^g ^flepreferenccs and re-execute the editor. 

Saving Preferences _ 

If you click on the Cancel button any changes you make will be ^ 
Ignored. If you click on the OK button the changes specified will 
remain In force until you quit the editor. If you would like the 
configuration made permanent then click on the Save button, 
which will create the file GENST2. inf on your disk. Next time you 
ruH CenST the configuration will be read from that file. 

Jh addition to saving the editor configuration the current setting 
fixtre the Assembly Options dialog box are also saved. 

Assembling & Running Programs 

All assembly and run options can be found on the Program menu. 

Assembly _ 


To assemble the program you are currently editing click on 
Assemble from the Program menu, or press Alt- a. The meaning of 
the various options, together with the assembly process itself Is 
detailed In the next chapter. The only option covered here is the 
Output to option. w 

GenST can assemble to disk, to memory, or nowhere - assembling 
to nowhere is ideal for syntax checking while assembly to memory 
is much faster than to disk and good for trying things out quickly. 

When you assemble to memory you have to specify the maximum 
program size in the Max: entry in the dialog box - normally this Is 
20k. enough for an average program with debug or a large program 
with no debug. This number determines the program buffer size, 
used by the assembler to store your assembled program. If you gel 
the program buffer full error when you assemble something you 
should change the number to be larger. There is of course a penalty 
for this - the bigger the program buffer size the smaller the amount 
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of memory left for the assembler Itself to use while assembling 
your program. If the assembler Itself aborts with Out of memory It 
means there Is not enough left for a complete assembly - you 
should reduce the buffer size, or if this still falls you will have to 
assemble to disk. 

When you assemble to disk the program buffer size number Is 
Ignored, giving maximum room In memory for the assembler Itself. 
If you haven't saved your program source code yet the file will be 
based on the name noname. 

W' After you click on Assemble or press Return the assembly process 
will start, described more fully In the next chapter. At the end of 
the assembly the program will wait for a key press, allowing you to 
read any messages produced, before returning you to the editor. If 
there were any errors the editor will go to the first erroneous line 
and display the error message In the status bar. Subsequent 
errors (and warnings) may be Investigated by pressing Alt-J. 

Running Programs _ 

If you click on Run from the Program menu or press Ait-x (execute) 
you can then run a program previously assembled Into memory. 
When your program finishes It will return you to the editor. If the 
assembly didn't complete normally for any reason then It Is not 
possible to run the program. 

If your program crashes badly you may never return to the editor, 
so If In doubt save your source code before using this, or the 
following command 


If only non-fetal errors occurred during assembly (e.g. 
undefined symbols) you will still be permitted to run your 
program, at your own risk. 
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Please Note 


When issuing a Run command from the editor the machine may 
seem to 'hang up' and not run the program. This occurs if the 
mouse is in the menu bar area of the screen and can be corrected 
by moving the mouse. Similarly when a program has finished 
running, the machine may not return to the editor. Again, moving 
the mouse will cure the problem. This is due to a feature of GEM 
beyond our control. 

Debug _ v ,J 

If you wish to debug a program previously assembled to memoiy 
click on Debug from the Program menu, or press Ait-D. This will 
Invoke MonST to deSs^ f^iir program, included any debugging 
information specified, piss&jig ctrl-c from MonST will terminate 
both your program aM debugger. The screen type selected Is 
determined by the RuriwfiSYGeM option, described below. 


MonST 


Clicking on MonST from the Program menu, or pressing Alt-M. will 
invoke MonST in a similar way to if it was invoked by double¬ 
clicking on the program Icon from the Desktop, but instantly, as It 
is already in memory. You will return to the editor on termination 
of the debugger. The screen type selected is determined by the Run 
with GEM option, described below. 
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Run with GEM 


<w 


Normally when the commands Run. Debug or MonST are used the 
screen Is Initialised to the normal GEM type, with a blank menu 
bar and patterned desktop. However If running a TOS program this 
can be changed to a blank screen with flashing cursor, by clicking 
on Run with GEM. or by pressing Alt-K. A check-mark next to the 
menu Item means GEM mode, no check mark means TOS mode. 
The current setting of this option Is remembered If you Save 
Preferences. 


Running a TOS program In GEM mode will look messy 
but work, but running a GEM program In TOS mode can crash the 


Jump to Error 


During an assembly any warnings or errors that occur are 
remembered, and can be recalled from the editor. Clicking on Jump 
to error from the Program menu, or pressing Ait-J will move the 
cursor to the next line in your program which has an error, and 
display the message In the status line of the window. You can step 
to the next one by pressing Alt-J again, and so on. letting you 
correct errors quickly and easily. If there are no further errors 
when you select this option the message No more errors will 
appear, or If there are no errors at all the message What errors! 
will appear. 

Run Otherv^_ 


This option lets you run other programs from within the editor, 
then return to it when they finish. Its main use Is to allow you to 
run programs you have assembled to disk, or to run the linker, 
without having to quit to the Desktop and double-click them. You 
can run both TOS and GEM programs using this command, 
subject to available memory. When you click on Run Other.., from 
the Program menu you will first be warned If you have not saved 
your source code, then the GEM File Selector will appear, from 
which you should select the program you wish to run. If it is a . tos 
or . ttp program you will be prompted for a command line, then 
the screen initialised suitably. 


HiSoft DevpacST 


Screen Editor 


Page 27 


Window Usage & Desk Accessories 


The GEM Editor Window 


The window used by the editor works like all other GEM windows, 
so you can move It around by using the move bar on the top of It. 
you can change Its size by dragging on the size box. and make It full 
size (and back again) by clicking on the full box. Clicking on the 
close box Is equivalent to choosing Quit from the File menu. 

Desk Accessories_ 


If your ST system has any desk accessories, you will find them in 
the Desk menu. If they use their own window, as Control Panel 
does, you will find that you can control which window is at the 
front by clicking on the one you require. For example, If you have 
selected the Control Panel it will appear In the middle of the screen, 
on top of the editor window. You can then move It around and If you 
wish It to lie 'behis^' *be editor window, you can do It by clicking on 
the editor wind*?*', -wtftSch brings It to the front, then re-sizing it so 
you can see sos8»- j*Rtt of the control panel's window behind It. 
When you want % fel'ig that to the front Just click on It and the 
editor window will go behind. The editor's cursor only flashes and 
the menus only work when the editor’s window is at the front. 

Automatic Double Clicking _ 

You may configure GenST to be loaded automatically whenever a 
source file Is double-clicked from the Desktop, using the Install 
Application option. 
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To do this you first have to dr-eidc on the extension you are going to 
use for your files, which w*$B&tancnd to be . S for source files. 
Having done this, go to the «. and click once on GENST2 .prg 
to highlight it. Next click ofe Application from the Options 
menu and a dialog box will appear; You should set the Document 
Type to be s (or whatever you require), and leave the GEM radio 
button selected. Finally click on the OK button (if you press Return 
it will be taken as Cancel). 

Having done this, you will return to the Desktop. To test the 
installation, double-click on a file with the chosen extension which 
'w must be on the same disk and In the same folder as GenST and the 
Desktop will load GenST. which will in turn load in the file of your 
choice ready for editing or assembly. 


To make the configuration permanent, you have to 
the Save Desktop option. 


Savedl Desk Accessory Users 


If you use the PATH feature «f. the fejt desk accessory 

then the restriction a$ having your data Slips to. the same folder and 
drive as your assembler describe® above is not relevant. The editor 
looks for the genstz .jtBK<«cojii%uratloiB itaily in the current 
directory (which is thffljfoto'w!w@s you do«bkW»cked on the data 
file), then using the swaterct fisesed^Sir preferences will 

put the . inf file In the aanae pl«c£ it Was tested from, or if it was 
not found then it wUij'be tllrectay. 

You may invoke SaVg^sitati .Within {liTe ©ditea at any time by 
^ pressing Shift-Clr. This will Wliy wem3lTith« desk accessory is 
Called SAVED! .ACC DStyCUiTbsWtdfststt 
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CHAPTER 3 
Macro Assembler 


Introduction 


GenST is a powerful, fast, full specification assembler, available 
instantly from within the editor or as a stand-alone program. It 
converts the text typed or loaded into the editor, optionally 
together with files read from disk. Into a binary file suitable for 
immediate execution or linking, or into a memory image for 
Immediate execution from the editor. 

Invoking the Assembler _ 

From the Editor _ 


V*/ 


The assembler is Invoked from the editor by clicking on Assemble 
from the Program menu, or by pressing Alt- a. A dialog box 
appears which looks like Figure 3.1 below. 

I Bssenblu Options I 
Progran type L EI II KD 

Synbols case M'lJ.MiMW I Independent! 

Debug info MM.M fworwan I Extended! 

List lIHiMl Screen II Printer ! I OlsK I 

I Output to] 


■.'friT^ I Henorg I nas 10_k * 

rwi l- 



Figure 3.1 - the Assembly Options dialog box 
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Program Type This lets you select between executable. GST or DRI 
format output. The differences between these are detailed later. 

Symbols case This lets you select whether labels are case 
dependent or not. If case Dependent is selected then Test and 
test would be different labels, If case Independent Is selected then 
they would be the same. 

Debug Info if you wish to debug your program using your original 
symbols you can select Normal or Extended debug modes. The 
advantage of extended debug Is that up to 22 characters of each 
symbol are included in the debug information, whereas normal 
mode restricts symbols to eight characters. 

List selecting Printer will divert the assembly listing to the current 
printer port, or selecting Disk will send the listing to a file based on 
the source filename, but with the extension . lst 

Output To This lets you select where the output file Is to be 
created. None means it Is 'thrown away', ideal for syntax checking 
a program; Memory means It is assembled into a buffer allowing it 
to be run or debugged Instantly from the editor without having to 
create a disk file;JplSk means a file will be created. The selection of 
the- name of thfe file can be left to the assembler, using rules 
described ehor 

'•She first two epJUtfrs® may also be specified in the source file using 

.T “ A . 

Kav&ig sriesstw? your required options you should click on the 
ASSSWifote button {or press Return) to start the assembly. At the 
esid Of yw’should press any key to return to the editor. 

it augf. attorn otxsuacsjgJ the cursor will be positioned on the first . 

ofiwrShg hr*;. W 

" '-i.o.vv« isembler_ 


If the . ttp version of the assembler Is invoked the without a 
command line the programmer will be asked for one. conforming 
to the rules below, or press Return to abort. At the end of assembly 
there will be a pause, pressing any key will exit the program. If a 
command line has been supplied the assembler will not wait for a 
key as it assumes it has been run from a CU or batch file. 
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Command Line Format 


The command line should be of the form 
main£ile <-options> [-options] 

The mainfile should be the name of the flic requiring assembly and 
If no extension Is specified defaults to .s. Options should follow 
this denoted by a - sign then an alphabetic character. Allowed 
options arc shown below together with equivalent OPT directives: 

^ b no binary file should be created 

c case Insensitive labels (opt c-) 

d debug (opt d+) 

l GST linkable code (opt L+) 

l 2 DRI linkable code (opt L2) 

o specify output filename (should follow Immediately alter o) 

p specify listing filename (should follow immediately after p). 
defaults to source filename with extension of . lst 

q pause for key press after assembly 
x extended debugging (OPT X+) 

The default is to create a executable binary file with a name based 
on the source file and output file type, no listing, with case 
sensitive labels. For example. 

test -b 

assembles test. s with no binary output file 
test -om:test.prg -p 

assembles test. s into a binary file m: test .prg and a listing file to 
test.lst 

test -12dpprn: 

assembles test. s into DRI linkable code with debug and a listing to 
the parallel port. (A listing to the serial port can be obtained by 
specifying aux : as the listing name). 


Output Filename 


GenST has certain rules regarding the calculation of the output 
filename, using a combination of that specified at assembly time 
(either in the Disk: filename field In the dialog box or using the -o 
option on the command line) and the OUTPUT directive: 

If an output filename Is explicitly given at assembly time then 
name=expllcit filename 

if the OUTPUT directive has not been used then ) 

name= source filename + .prg, .bin or .0 
elsclf the OUTPUT directive specifies an extension then 
name=source filename + extension in OUTPUT 

else 

name=name In OUTPUT 

Assembly Process __ 

GenST is a two-pass assembler; during the first pass it scans all 
the text in memory and from disk if required, building up a symbol 
table. If syntax errors are found on the first pass assembly these 
will be reported and assembly will stop at the end of the first pass, 
otherwise, during the second pass the instructions are converted 
Into bytes, a listing may be produced if required and a binary file 
can be created on the disk. During the second pass any further 
errors and warnings will be shown, together with a full listing and 
symbol table if required. 

During assembly, any screen output can be paused by pressing 
Ctrl-s. pressing ctrl-o will resume It. Assembly may be aborted 
by pressing ctrl-c. although doing so will make any binary file W' 
being created Invalid as it will be incomplete and should not lie 
executed. 

Assembly to Memory __ 

To reduce development time GenST can assemble programs to 
memory, allowing immediate execution or debugging from the 
editor. To do this a program buffer is used, the size of which is 
specified in the Assembly Options dialog box. If no debug option is 
specified the size given can be Just a little larger than the output 
program, but if either form of debug is required a ?faw£& larger 
buffer may be needed. 
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A program running from memory Is Just like any normal 
GEMDOS program and should terminate using either pterm or 
ptermO GEMDOS calls, for example 

clr.w -(a7) 
crap il 

Programs may self-modlfy If required as a re-executed program 
will be In its original state. 

, The program buffer size and current assembly options can be 
'w- made the default on re-loading the editor if Save Preferences is 


Binary file types 


There are six types of binary files which may be produced by 
GenST, for different types of applications. They arc distinguished 
by the extension on the filename: 


w. 


. prg GEM-type application i.e. one that uses windows 
.TOS TOS-type application i.e. one that doesn't use windows 
. ttp TOS-type application that requires a command line 
.ACC desk accessory program file 

0TM non-executable file suitable for linking with GST-format files 
and libraries 

non-executable file suitable for linking with DRI-format files 
and libraries 


also assemble executable code directly to memory when 
using the integrated version allowing very fast edit-assemble- 
debug-run times. 


The first three are double-clickable, can be run from the Desktop 
and are known as executable. They differ in the initialisation 
performed before the execution. With . prg files the screen is 
cleared to the Desktop's pattern, while with the other two the 
screen clears to white, the flashing cursor appears and the mouse 
is disabled. When you double-click a .ttp file the Desktop will 
prompt you for a command line to pass to it. 


HiSoft DevpacST 


Assembler 


Page 35 




.ACC files are executable flies but cannot be double-clicked on from 
the Desktop. They will only run successfully when executed by the 
AES during the boot sequence of the machine. 

.BIN and .0 files cannot be run Immediately, but have to be read 
into a linker, usually with other sections, and are known as 
linkable object modules. There are two different linker formats on 
the ST. .bin files are GST format. .0 files are DR1 format. The 
differences between these are discussed later in this chapter. 

The above extensions are not absolute rules; for example. If you . 
have a TOS type program you may give it a . prg extension and use W 1 
the Install Application function from the Desktop, but it's usually 
tiiueh easier to use the normal extensions. One exception is for 
programs which are designed to be placed in the AUTO folder so 
they execute during the boot sequence. They have to be TOS type 
programs, but need the extension . prg for the boot sequence to 
find them. 


Certain versions of the French ST ROMs do not 
recognise .ttp files from the Desktop so they have to be renamed 
.tos then Installed as TOS Takes Parameters. 

Types of code _ _ 

Unlike most 8-bit operating systems, but like, rsfraft 16-bit 
systems, an executable program under GEMDOS wiS Faft &b loaded 
at a particular address but. Instead, be loaded «jt ®a address 
depending on the exact free memory configuration si dme. 

To get around the problem of absolute addressing the ST file V * B ^ 
format includes relocation information allowing GEMDOS to 
relocate the program after it has loaded it but before running it. For 
example the following program segment 

raove.l #string,aO 


string dc.b 'Press any key',0 
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places the absolute address of string into a register, even though 
at assembly time the real address of string cannot possibly be 
known. Generally the programmer may treat addresses as 
absolute even though the real addresses will not be known to him. 
while the assembler (or linker) will look after the necessary 
relocation Information. 


For certain programs, normally games or for cross- 
machine development an absolute start address may be required, 
for this reason the ORG directive is supported. 


The syntax of the assembler will now be described. 


Assembler Statement Format 


Each line that Is to be processed by the assembler should have the 
following format: 

Label Mnemonic Operand(s) Comment 

start move.l do,(a0)+ store the result 

Exceptions to this are comment lines, which are lines starting with 
an asterisk or semi-colon, and blank lines, which are Ignored. Each 
field has to be separated from the others by white space - any 
number or mixture of space and tab characters. 

Label field_ 


The label should normally start at column 1, but if a label is 
required to start at another position then it should be followed 
Immediately by a colon (.). Labels are allowed on all instructions, 
but are prohibited on some assembler directives, and absolutely 
required on others. A label may start with the characters A-Z, a-z. 
or underline ( ). and may continue with a similar set together with 
the addition of the digits 0-9 and the period (.). 
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Labels starling with a period are local labels, described later. Macro 
names and register equate symbols may not have periods in them, 
though macro names may start with a period. By default the first 
127 characters of labels are significant, though this can be reduced 
If required. Labels should not be the same as register names, or the 
reserved words SR. ccr or usp. 

By default labels arc case-sensitive though this may be changed. 
Some example legal labels are: 

test. Test, TEST, _test.end, tests, _5test 

Some example illegal lafe&sase: 

5test, _se, test>. 

There are certain reserved symbols in GenST. denoted by starting 
with two underline characters. These are_ lk._rs and_62. 

Mnemonic Field_ 


The mnemonic field comes after the label field and can consist of 
68000 assembler Instructions, assembler directives or macro calls. 
Some instructions and directives allow a size specifier, separated 
from the mnemonic by a period. Allowed sizes are .b for byte, .w for 
word, . L for long and .S for short. Which size specifiers are allowed 
In each particular case depends on the particular instruction or 
directive. GenST is case-insensitive to mnemonic and directive 
names, so Move Is the same as move and the same as mOvE, for 
example. 

Operand Field _ 

For those Instructions or directives which require operands, this 
field contains one or more parameters, separated by commas. 
GenST is case-insensitive regarding register names so they may 
be in either or mixed case. 

Comment Field__ 


Any white space not within quotation marks found after the 
expected operand(s) is treated as a delimiter before the start of the 
comment, which will be ignored by the assembler. 
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Examples of valid lines 


move.1 dO,(aO)+ comment is here 
loop TST.W dO 
lonely.label 


* this is a complete line of comment 

W 

; and so is this 

indented: link A6,#-10 make room 
a_string: dc.b 'spaces allowed in quotes' a string 

Expressions _ 

GenST allows complex expressions and supports full operator 
precedence, parenthesis and logical operators. 

Expressions are of two types - absolute and relative - and the 
distinction Is Important. Absolute expressions are constant values 
which are known at assembly-time. Relative expressions are 
program addresses which are not known at assembly-time as the 
GEMDOS loader can put the program where it likes in memory. 
Some instructions and directives place restrictions on which types 
are allowed and some operators cannot be used with certain type- 
combinations. 

Operators ___ 

The operators available. In decreasing order of precedence, are: 

monadic minus (-) and plus (+) 
bitwise not (-) 

shift left («) and shift right (») 
bitwise And (&), Or (!) and Xor (') 
multiply (*) and divide (/) 
addition (+) and subtraction (-) 
equality (-). less than (<), greater than (>) 
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The comparison operators are signed and return 0 if false wt -.1 
($FFFFFFFF) if true. The shift operators take the left hand opsrastd 
and shift it the number of bfts specified in the right hand apertwsl 
and vacated bits are filled with zeroes. 

This precedence can be overridden by the use of parentheses ( and 
). With operators of equal precedence, expressions are evaluated 
from left-to-right. Spaces in expressions (other than those within 
quotes as ASCII constants) are not allowed as they are taken as 
the separator to the comment. 

All expression evaluation Is done using 32-blt signed-integer 
arithmetic, with no checking of overflow. 

Numbers_ 


Absolute numbers may be in various forms: 

decimal constants, e.g. 1029 
hexadecimal constants, e.g. $l2f 
octal constants, e.g. 6730 
binary constants, e.g. %1100010 
character constants, e.g. ’X’ 

S is used to denote hexadecimal numbers, % for binary numbers. 0 
for octal numbers and single ■ or double quotes •• for character 
constants. 


Character Constants 


Whlcte^fl^jitote is used to mark the start of a string must also be 
used #[• ‘fejSifete its end and quotes themselves may be used in 
strings delimited with the same quote character by having It occur 
twice. Character constants can be up to 4 characters in length and 
evaluate to right-justified longs with null-padding if required. For 
example, here are some character constants and their ASCII and 
hex values: 

"Q" Q $00000051 

•hi 1 hi $00006869 

"Test" test $54657374 

"ifs" it's S6974277C 

'it"s' it's $69742770 
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Strings used in DC.B statements follow slightly different 
justification rules, detailed with the directive later. 

Symbols used in expressions will be either relative or absolute, 
depending on how they were defined. Labete pitfetei the source will 
be relative, while those defined using the E’i?.y #S;'Sctlve will be the 
same type as the expression to which they gloated. 

The use of an asterisk (*) denotes the value sit*5a program counter 
at the start of the instruction or directive ws4 to always a relative 
quantity. 

Allowed Type Combinations _ 

The table in Figure 3.2 summarises for each operator the results of 
the various type combinations of parameter and which 
combinations are not allowed. An R denotes a Relative result, an A 
denotes absolute and a • denotes that the combination is not 
allowed and will produce an error message if attempted. 



A op A 

A op R 

Rop A 

Rop R 

Shift operators 

A 




Bitwise operators 

A 




Multiply 

A 




Divide 

-5- 


* 


Add 

A 

R 

k 


Subtract 

—s— 




Comparisons 

A 





Figure 3.2 - Allowed Type Combinations 
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Addressing Modes 


The available addressing modes are shown in the table below. 
Please note that GenST is case-lnsensitlve when scanning 
addressing modes, so do and a3 are both valid registers. 


Form Meaning 



R denotes index register, either A or D 
J denotes size, either W or L. when omitted defaults to 


Example 


(Al) 
IA5) + 


“ (AO) 

20(A7) 

4 (A6, D4 . L) 
$0410.W 
$12000.L 


NEXTIPC, A2.W) 
126 


When using address register Indirect with Index the displacement 
may be omitted, for example 


move. 1 (a3,d2.1), dO 

will assemble to the same as 


move.1 0(a3,d2.1), dO 

Special Addressing Modes _ 

CCR condition code register 

SR status register 

USP user stack ’ 

In addition to the alfei#'can be used in place of A7 in any 
addressing mode. e.g. .w) 

The data and address registers can also be denoted by use of the 
reserved symbols R0 through R15. R0 to R7 are equivalent to DO to 
D7. R8 to R15 are equivalent to AO to A7. This is Included for 
compatibility with other assemblers. 
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Local Labels 


GenST supports local labels, that Is labels which are local to a 
particular area of the source code. These are denoted by starting 
with a period and are attached to the last non-local label, for 
example: 


lenl 
. loop 




len2 


move.l 4(sp),a0 
tst.b (a0)+ 

bne.s ■loop 


tst.b 


4(sp),a0 
- (aO) 


There are two labels called . loop In this code segment but the first 
Is attached to lenl. the second to len2. 

The local labels . w and . l are not allowed to avoid confusion with 
the absolute addressing syntax. 

Symbols and Periods __ 

Symbols which include the period character can cause problems 
with GenST due to absolute short addressing. 

The Motorola standard way of denoting absolute short addresses 
causes problems as periods are considered to be part of a label, best 
Illustrated by an example: 


move.l vector.w,dO 

where vector Is an absolute value, such as a system variable. This 
would generate an undefined label error, as the label would be 
scanned as vector.w. To get around this, the expression, in this 
case a symbol, may be enclosed In brackets, e.g. 


move.l (vector).w,dO 

though the period may still be used after numeric expressions, e.g. 


move.l $402.w,dO 
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GenST version 1 also supported the use of \ Instead of 
a period to denote short word addressing and this is still 
supported In this version, but this is not recommended due to the 
potential for \w and \L to be mistaken for macro parameters. 

Instruction Set 


Word Alignment _ 

All instructions with the exception of DC.B and DS.B are always 
assembled on a word boundary. Should you require a DC.B 
explicitly on a word boundary, the EVEN directive should be used 
before it. Although all Instructions that require it are word-aligned, 
labels with nothing following them are not word-aligned and can 
have odd values. This is best illustrated by an example: 

nop this will always be word aligned 

dc.b 'odd' 

start 

tst.l (aO) + 


The above code would not produce the required result as start 
would have an odd value. To help in finding such instructions the 
assembler will produce an error if it finds an odd destination in a 
BSR or BRA operand. Note that such checks are not made on any 
other Instructions, so it is recommended that you jWWJtrtte such 
labels with EVEN directives If you require them to be whi’4 aligned. A 
common error is deliberately not to do this, as y®2 know the 
preceding string is an even number of bytes long. All will be well 
until the day you change the string... 

instruction Set Extensions_ 


The complete 68000 instruction set is supported and certain 
shorthands are automatically accepted, detailed below. A complete 
description of the instruction set including syntax and addressing 
is 6dm can be found in any 68000 reference guide or In the 
supplied Pocket Guide 
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Condition Codes. 

The condition codes HS and LO are supported in Bcc. 

DBcd : 4Sji4:wbc instructions, equivalent to CC and CS. respectively. 

Branch instructions 

To force a short branch use Bcc.B or Bcc.S. to force a word branch 
use Bcc.W or to leave to the optimlser use Bcc. Bcc.L is supported 
for compatibility with GenST 1 with a warning as it is. strictly 
speaking, a 68020 Instruction. A BRA.S to the immediately 
'w following Instruction is not allowed and is converted, with a 
warning, to a NOP. A BSR.S to the Immediately following 
Instruction is not allowed and will produce an error. 

BTST Instruction 

BTST is unique among bit-test Instructions Irt supporting PC- 
relative addressing modes. 

CLR Instruction 

CLR An is not allowed, use SUB.L An An Instead (though note that 
the flags are not effected). 

CMP Instruction 

If the source is immediate then CMPI is used, else if the destination 
is an address register then CMPA is used, else if both addressing 
modes are post-increment then CMPM is used. 

DBcc Instruction 

DBRA is accepted as an equivalent to DBF. 

ILLEGAL Instruction 

This generates the op-code word $4AFC. 

LINK Instruction 

displacement Is positive or not even a warning will be given. 
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MOVE from CCR Instruction 


This Is a 68010 and upwards instruction, converted with a 
warning to MOVE from SR. 

MOVE9 Instruction 

If the data is in the range 128-255 inclusive a warning will be given. 
It may be disabled by specifying a long size on the Instruction. 

Assembler Directives 


Certain pseudo-mnemonics are recognised by GenST. These 
assembler directives, as they are called, are not (normally) decoded 
Into opcodes, but instead direct the assembler to take certain 
actions at assembly time. These actions have the effect of changing 
the o*$ect code produced or the format of the listing. Directives are 
spanned exactly like executable Instructions and some may be 
preceded by a label (for some it is obligatory) and may be followed 
by a comment. If you put a label on a directive for which it not 
i'lJlRvant. the result will be undefined but will usually result In the 
label being ignored. 

Each directive will now be described in turn. Please note that the 
case of a directive name is not Important, though they generally 
are shown in upper case. The use of angled brackets (< >) in 
descriptions denote optional items, ellipses (...) denote repeated 
items. 

Assembly Control _ 


end 

This directive signals that no more text is to be examined on the 
current pass of the assembler. It Is not obligatory. 

INCLUDE filename 

This directive will cause source code to be taken from a file on disk 
and assembled exactly as though it were present In the text. The 
directive must be followed by a filename in normal GEMDOS 
format. 
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If the filename has a space In It the name should be enclosed In 
single or double quotes. A drive specifier, dfeg&gjj? and extension 
may be included as required, e.g. 

include b:constants/header.s 

Include directives may be nested as deeply as memory allows and If 
any error occurs when trying to open the file or read ft. assembly 
will be aborted with a fatal error. 

If no drive or pathname Is specified, that of the main source file will 
be used when trying to open the flic. 


The more memory the better. GenST will read the 
whole of the file in one go If It can and not bother to re-read the file 
during pass 2. 


INCBIN filename 

This takes a given binary file and Includes it. verbatim, into the 
output file. Suggested uses include screen data, sprite data and 
ASCR fifes. 


OPT option <,opfion> ... 

This allows control over various options within GenST and each 
one Is denoted by a single character normally followed by a + or - 
sign. Multiple opUons may be specified, separated by commas. The 
allowed options are: 

Option C - Case-sensitivity and significance 

By default. GenST is sensitive to label case.and labels are 
significant to 127 characters. This can be overridden, using C- for 
case-sensitivity, or c+ for case-insensitivity. The significance may 
be specified by specifying a decimal number between the C and the 
sign, for example Cl6+ denotes case insensitive labels with 16 
character significance. This option may be used at any time In a 
program but normally only makes sense at the very beginning of a 
source file. 


HfSoft DevpacST 


Assembler 


Page 47 


Option D - Debugging Information 

The GEMDOS binary file format supports the Inclusion of a 
symbol table at the end. which may be read by debuggers such as 
MonST and can be extremely useful when debugging programs. By 
default this Is switched off but It may be activated with D+ and 
deactivated with D-. The first 8 characters only of all relative labels 
are written to the file and will be upper-cased if GcnST Is In case- 
lnsensltlvc mode. The 8-charactcr limit Is due to the DRI standard 
file format and may be Improved on by using the Extended Debug 
option, described below. 

Option L - Linker Mode 

The default for GenST Is to produce executable code but L+ will 
make It produce GST linkable code. L2 will make It produce DRI 
linkable code, or l- will make It revert to executable. This directive 
must be the very first line In the first text file. 

Option M - Macro Expansions 

When an assembly listing Is produced, macro calls are shown in 
the same form as In the source. If you wish the Instructions within 
macros to be listed, use M+. while m- will disable the option. You can 
use this directive as often as required. 

Option O - Optimising 

GenST Is capable of optimising certain statements to faster and 
smaller versions. By default all optimising Is off but each type can 
be enabled and disabled as required. This opUon has 

OPT OI+ will optimise backward branches to shorf.'ifvlthr.fe ! 
range, can be disabled with Ol- . ■ 

OPT 02+ will optimise address register indirect wftly ’ / 

displacement addressing modes to addrie^$! ■ 

Indirect, If the displacement evaluates to zero, and can 

be disabled with 02-. For example 

move.1 next(aO), d3 

will be optimised to 

move.1 (aO),d3 

if the value of next Is zero. 
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OPT O* will turn all optimising on 
OPT O- will turn all optimising off 
OPT Ol-. OPT 02- 

wlll disable the relevant optimisation 

OPT OW- will disable the warning messages generated by each 
optimisation. OW+ will enable them. 

If any optimising has been done during an assembly the number of 
optimisations made and bytes saved will be shown at the end of 
assembly. 

Option P - Position Independent checks 

With this option enabled with p+ GenST will check that all code 
generated is position-independent, generating errors on any lines 
which require relocation. It can be disabled with p- and defaults to 
off. 

Option S - Sy«<fl‘X'able 

When a listing Is turned on a symbol table will be produced at the 
end. If you wish to change this, s- will disable It. while s+ will re¬ 
enable it. If you use this directive more than once the last one will be 
taken Into account. 

Option T - Type Checking 

GenST can often spot programming errors as it checks the types 
of certain expressions. For some applications or styles of 
programming this can be more of a hindrance than a help so T- 
W will turn checks off, t* turning them back on. For example the 
program segment 

main bsr initialise 

lea main(a6),a0 
move.l (main).w.aO 

will normally produce an error as main is a relative expression 
whereas the assembler expects an absolute expression in both 
cases. However if this code is designed to run on another 68000 
machine this may be perfectly valid so the type checking should be 
disabled. 
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Option W - Warnings 

If you wish to disable the warnings that GenST can produce, you 
can do so with w-. To re-enable them, use w+. This directive can be 
used as often as required. 

Option X - Extended Debug 

This Is a special version of option D which uses the HiSoft 
Extended Debug format to generate debugging information with 
symbols of up to 22 character significance. 

Qpitaft Summary _ ^ 

lEte defaults are shown in brackets after each option description: 

C case-sensitivity & significance (C127+) 

D include debugging information (d-) 

L- produce executable code (default) 

L+ produce GST linkable code 
L2 produce DRI linkable code 
M expand macros in listing (m+) 

O optimising control (0-) 

P position Independent code checks (P-) 

S symbol table listing 

T type checking (t+) 

W warning control (w+) 

X Extended debug (x-J 

For example, the line 

opt m+,s+,w- 

will turn macro expansions on, enable the symbol table list and ^ 
turn warnings off. 

<label> EVEN 

This directive will force the program counter to be even, i.e. word- 
aligned. As GenST automatically word-allgns all instructions 
(except DC.Bs and DS.Bs) it should not be required very often, but 
can be useful for ensuring buffers and strings are word-aligned 
when required. 
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CNOP offset,alignment 

This directive will align the program counter using the given offset 
and alignment. An alignment of 2 means word-aligned, an 
alignment of 4 means long-word-aligned and so on. The alignment 
Is relative to the start of the current section. For example. 

cnop 1,4 

aligns the program counter a byte past the next long-word 
boundary. 

<label> DC.B expression*:,expression ... 

<label> DC.W expression*:,expression> ... 

<label> DC.L expression*:,expression> ... 

These directives define constants In memory. They may have one 
or more operands, separated by commas. The constants will be 
aligned on word boundaries for DC.W and DC.L. No more than 128 
bytes can be generated with a single DC directive. 

DC.B treats strings slightly differently to those In normal 
expressions. While the rules described previously about quotation 
marks still apply, no padding of the bytes will occur and the length 
of any string can be up to 128 bytes. 

Be very careful about spaces in DC directives, as a space is the 
delimiter before a comment. For example, the line 

dc.b 1,2,3 ,4 

will only generate 3 bytes - the , 4 will be taken as a comment. 

* W <label> DS.B expression 

<label> DS.W expression 

<label> DS.L expression 

These directives will reserve memory locations and the contents 
will be Initialised to zeros. If there Is a label then It will be set to the 
start of the area defined, which will be on a word boundary for 
DS.W and DS.L directives. There Is no restriction on the size, 
though the larger the area the longer It will take to save to disk. 
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For example, all of these lines will reserve 8 bytes of space, in 
different ways: 



<label> DCB.B number,value 

<label> DCB.W number,value 

<label> DCB.L number,value 

This directive allows constant blocks of data to be generated of the 
size specified, number specifies how many times the value should 
be repeated. 

FAIL 

This directive will produce the error user error. It can be used for 
such things as warning the programmer if an incorrect number of 
parameters have been passed to a macro. 

OUTPUT filename 

This directive sets the normal output filename though can be 
overridden by specifying a filename at the start of assembly. If 
filename starts with a period then it is used as an extension and 
the output name is built up as described previously. 

_G2 (reserved symbol) 

This is a reserved symbol that can be used to detect whether 
GenST 2 is being used to assemble a file using the IFD conditional. 
The value of this symbol depends on the version of the assembler 
and is always absolute. 

Repeat Loops _ 


It is often useful to be able to repeat one or more instrucUons a 
particular number of times and the repeat loop construct allows 
this. 
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<label> REPT expression 
ENDR 

Lines to be repeated should be enclosed within REPT and ENDR 
directives and will be repeated the number of times specified in the 
expression. If the expression is zero or negative then no code will be 
generated. It Is not possible to nest repeat loops. For example 

REPT S12/4 copy a sector quickly 
move.1 <a0) +, (al) + 

ENDR 


Program Safest should not be defined within repeat 
loops to prevent label defined twice errors. 

Listing Control __ 

LIST 

This will turn the assembly listing on during pass 2, to whatever 
device was selected at the start of the assembly (or to the screen if 
None was initially chosen). All subsequent lines will be listed until 
an END directive is reached, the end of the text is reached, or a 
NOLIST directive is erewnsitered. 

Greater control over listing sections of program can be achieved 
using LIST + or LIST - dtetffittves. A counter is maintained, the state of 
which dictates whether listing is on or off. A LIST + directive adds 1 
to the counter and a LIST - subtracts 1. If the counter Is zero or 
positive then listing is on. if it is negative then listing is off. The 
default starting value is -1 (l.e. listing off) unless a listing is 
specified when the assembler was Invoked, when It is set to 0. This 
system allows a considerable degree of control over listing 
particularly for include files. The normal LIST directive sets the 
counter to 0, NOLIST sets it to -1. 

NOLIST 

This will turn off any listing during pass 2. 
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When a listing is requested onto a printer or to disk, the output Is 
formatted into pages, with a header at the top of every page. The 
header itself consists a line containing the program title, date, time 
and page number, then a line showing the program title, then a 
line showing the sub-title, then a blank line. The date format will be 
printed in the form dd/mm/yy. unless the assembler is running on 
a US Atari ST. in which case the order is automatically changed to 
mm/dd/yy. Between pages a form-feed character (ASCII FF. value 
12) is issued. 

PLEN expression 

This will set the page length of the assembly listing and defaults to 
60. The expression must be between 12 and 255. 

LLEN expression 

This will set the line width of the assembly listing and defaults to 
132. The value of the expression must be between 38 and 255. 

TTL string 

This will set the title printed at the top of each page to the given 
string, which may be enclosed in single quotes. The first TTL 
directive will set the title of the first printed page. If no title Is 
specified the current include file name will be used. 

SUBTTL string 

Sets the sub-title printed at the top of each page to the given string, 
which may be enclosed in single quotes. The first such directive will 
set the sub-title of the first printed page. 

SPC expression 

This will output the number of blank lines given in the expression 
in the assembly listing, if active. 

PAGE 

Causes a new page in listing to be started. 



LISTCHAR expression*:,expression ... 

This will send the characters specified to the listing device (except 
the screen) and is Intended for doing things such as setting 
condensed mode on printers. For example, on Epsons and 
compatibles the line 

listchar 15 

will set the printer to 132-column mode. 

FORMAT param©ter<,parameter> ... 

This allows exact control over the listed format of a line of source 
code. Each parameter controls a field In the listing and must 
consist of a digit from 0 to 2 Inclusive followed by a + (to enable the 
field) or a - (to disable It): 

0 line number, In decimal 

1 section name/number and program counter 

2 hex data In words, up to 10 words unless printer Is less than 
80 characters wide, when up to three words are listed. 

Label Directives_ 


label EQU expression 

This directive will set the value and type of the givers label io the 
result of the expression. It may not Include forward references, or 
external labels. If there Is any error in the expression, the 
assignment will not be made. The label Is compulsory and must not 
be a local label. 

label = expression 

Alternate form of F.QU statement. 

label register 

This directive allows a data or address register to be referred to by a 
user-name, supplied as the label to this directive. This is known as 
a register equate. A register equate must be defined before It Is 
used. 
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label SET expression 

This Is similar to EQU, but the assignment is only temporaiy and 
can be changed with a subsequent SET directive. Forward 
references cannot be used In the expression. It is especially useful 
for counters within macros, for example, using a line like 

zcount set zcount+1 

(assuming zcount is set to 0 at the start of the source). At the start 
of pass 2 all SET labels are made undefined, so their values will 
always be the same on both passes. 

label REG register-list 

This allows a symbol to be used to denote a register list within 

MOVEM instructions, reducing the likelihood of having the list at 
the start of a routine different from the list at the end of the 
routine. A label defined with REG can only be used in MOVEM 
instructions. 

<label> RS.B expression 

<label> RS.W expression 

<label> RS.L expression 

These directives let you set up lists of constant labels, which is very 
useful for data structures and global variables and is best 
illustrated by a couple of examples. 

Let's assume you have a data structure which consists of a long 
word, a byte and another long word, in that order. To make you 
code more readable and easier to update should the structure 
change, you could use lines such as 

rsresec 
rs.l 1 

rs .b 1 

rs.l 1 

then you could access^$$#lth lines like 

move.l d_where(a0),a2 

tst.b d_flag(aO) 


d_next 

d_flag 
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As another example let's assume you are referencing all your 
variables off register A6 (as done In GenST and MonST) you could 
define them with lines such as 

onstace rs.b 1 
start rs.X 1 
end rs.l 1 

You then could reference them with lines such as 

move.b onstate(a6),dl 
move.l start (a6),d0 
cmp.l end(a6),d0 

Each such directive uses its own Internal counter, which Is reset to 
0 at the beginning of each pass. Every time the assembler comes 
across the directive It sets the label according to the current value 
(with word alignment If It Is .W or .L) then Increments It according 
to the size and magnitude of the directive. If the above definitions 
were the first RS directives, onstate would be 0. start would be 2 
and end would be 6. 

RSRESET 

Hals directive will reset the Internal counter as used by the RS 
directive. 


RSSET expression 

this allows the RS counter to be set to a particular value. 

_RS (reserved symbol) 

This is a reserved symbol having the current value of the RS 
counter. 

Conditional Assembly _ 

Conditional assembly allows the programmer to write a 
comprehensive source program that can cover many conditions. 
Assembly conditionals may be specified through the use of 
arguments. In the case of macros, and through the definition of 
symbols In EQU or SET directives. Variations In these can then 
cause assembly of only those parts necessaiy for the specified 
conditions. 
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There are a wide range of directives concerned with conditional 
assembly. At the start of the conditional block there must be one of 
the many IF directives and at the end of each block there must be 
an ENDC directive. Conditional blocks may be nested up to 65535 
levels. 

Labels should not be placed on IF or ENDC directives as the 
directives will be Ignored by the assembler. 

IFEQ expression 

IFNE expression 

IFGT expression 

IFGE expression 

IFLT expression 

IFLE expression 

These directives will evaluate the expression, compare It with zero 
and then, turn conditional assembly on or off depending on the 
result., conditions correspond exactly to the 68000 condition 
codes.,SaS , :ifi^miple, If the label debug had the value 1. then with the 
follow 


IFEQ DEBUG 

logon dc.b 'Enter a command:',0 

ENDC 

IFNE DEBUG 

opt d+ labels please 

logon dc.b 'Yeah, gimme man:',0 

ENDC 

the first conditional would turn assembly off as 1 Is not ESM«©,. 
while the second conditional would turn It on as 1 is NE to 0. 


The expressions used in these conditional statements must 
evaluate correctly. 
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IFD 

IFND 


label 

label 


These directives allow conditional control depending on whether a 
label Is defined or not. With IFD. assembly Is switched on If the label 
Is defined, whereas with IFND assembly is switched on If the label Is 
not defined. These directives should be used with care otherwise 
different object code could be generated on pass 1 and pass 2 which 
will produce Incorrect code and generate phasing errors. Both 
directives also work on reserved symbols. 

IFC string r,'strlng2' 

This directive will compare two strings, each of which must be 
surrounded by single quotes. If they are Identical then assembly Is 
switched on. else it Is switched off. The comparison Is case- 
sensitive. 


IFNC ‘string l' 1 , strlng2' 

This directive Is similar to the above, but only switches assembly 
on If the strings are not Identical. This may at first appear 
somewhat useless, but when one or both of the parameters are 
macro parameters it can be very useful, as shown In the next 
section. 


ELSEIF 

This directive toggles conditional assembly from on to off, or vice 
versa. 


ENDC 

* w This directive will terminate the current level of conditional 
assembly. If there are more IFs than ENDCs an error will be 
reported at the end of the assembly. 

IIF expression instruction 

This is a short form of the IFNE directive allowing a single 
Instruction or directive to be assembled conditionally. No ENDC 
should be used with IIF directives. 
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Macro Operations 


GenST fully supports extended Motorola-style macros, which 
together with conditional assembly allows you greatly to simplify 
assembly-language programming and the readability of your code. 

A macro Is a way for a programmer to specify a whole sequence of 
Instructions or directives that are used together very frequently. A 
macro Is first defined, then Its name can be used In a macro call like 
a directive with up to 36 parameters. 

label MACRO 

This starts a macro definition and causes GenST to copy all 
following lines to a macro buffer until an ENDM directive is 
encountered. Macro definitions may not be nested. 

ENDM 

This terminates the storing of a macro definition, after a MACRO 
directive. 


MEXIT 

This stops prematurely the current macro expansion and is best 
Illustrated by the INC example given later. 

NARG (reserved symbol) 

This Is not a directive but a reserved symbol. Its value Is the 
number of parameters passed to the current macro, or 0 If used 
when not within any macro. If GenST Is in case-sensitive mode 
then the name should be all upper-case. 
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4ggg o Rotameters _ , [ 

‘fitftsk a macro has been defined with Jj*e MAfSSO C'jectlve It can be 
•Wf'V-cd by using Its name as a fqttow<rd by up to 36 

;,Vs. meters. In the macro Itself the paraotetetS n.-ay be referred to 
.V’ .s-mg the backslash character (\> fcScwi by «■ alpha-numeric 
or a-z) which will be replaces X*«fc th? relevant parameter 

when expanded or wh mt».. . - -.s given. There !s 

also the special mac* ■?*jzc appended to 

the macro call B J j^B tE PWi g « macro 

parameter Is to Inc . i the parameter 

should be enclosed ;%£$?■•>, *J* ,S case a * 

symbol may be lnclu- ! : ^i^<j^i*i;?^2i^g^^ii^@>ecllylng ». 

A special form of i*>- : » - f Z~?*7£uZ. w £*'^^ onversion of a 
symbol to a declma^tm5®Jfe^ , ?^^^2-Cj 1 8 lts - usln 8 the 
syntax \<symbo 1 denoting hex 

expansion. The symfc^t^*-tf’ S? ^2.te at the time of 

the expansion. 

The parameter \0 labels with 

each macro call and expanded by the 

sequence _nnn where nnn Is a number which Increases by one with 
every macro call. It may be expanded up to five digits for very large 
assemblies. 


A true \ may be Included In a macro definition by specifying \\. 

A macro call may be spread over more than one line, particularly 
useful for macros with large numbers of parameters. This can be 
done by ending a macro call with a comma then starting the next 
line with an & followed by tabs or spaces then the continuation of 
the parameters. 

In the assembly listing the default Is to show Just the macro call 
and not the code produced by it. However, macro expansion 
listings can be switched on and off using the OPT M directive 
described previously. 

Macro calls may be nested as deeply as memory permits, allowing 
recursion if required. 

Macro names are stored in a separate symbol table to normal 
symbols so will not clash with similarly-named routines, and may 
start with a period. 
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Macro Examples 


Example 1 - Calling the BDOS 

As the first example, the eeneffig &BKIDOS calling-sequence for the 
BDOS is: 

put a word parameter o&l&aSsSack 

Invoke a TRAP #1 

correct the stack afterwards 

A macro to follow these specifications could be w 1 

call_gemdos MftC&rt 

move. w function 

trap #1 

lea \2(a7),a7 correct stack 

ENDM 

The directives are In capitals only to make them stand out: they 
don't have to be. If you wanted to call this macro to use GEMDOS 
function 2 (print a character) the code would be 

move.w #'X*,-(a7) 

call_gemdos 2,4 

When this macro call Is expanded. \i is replaced with 2 and \2 Is 
replaced with 4. \o. if it occurred in the macro, would be w as no size 
is given on the call. So the above call would be assembled as: 

move.w 12,-(a7) 
trap SI 
lea 4(a7),a7 

Example 2 - an INC instruction 

The 68000 does not have the INC Instruction of other processors, 
but the same effect can be achieved using an ADDQ #1 instruction. 

A macro may be used to do this, like so: 

inc MACRO 

IFC ".•U* 

fail missing parameter! 

MEXIT 

ENDC 

addq.\0 #1,\1 
ENDM 
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An example call would be 
inc.l aO 
which would expand to 


addq.l II, aO 

The macro starts by comparing the first parameter with an empty 
string and causing an error message to be issued using fail If it is 
equal. The mexit directive is used to leave the macro without 
L, expanding the rest of it. Assuming there Is a non-null parameter, 
the next line does the addq Instruction, using the \0 parameter to 
get the correct size. 

Example 3 - A Factorial Macro 

Although unlikely actually to be used as it stands, this macro 
defines a label to be the factorial of a number. It shows how 
recursion can work In macros. Before showing the macro, it Is 
useful to examine how the same thing would be done in a high-level 
language such as Pascal. 


function factor(n:integer):integer; 
begin 

if n>0 then 

factor:=n*factor(n 

else 

factor:=1 




i-l> 


'w 


The macro definition for this uses the SET directive to do the 
multiplication n*(n-l)*(n-2) etc. In this way: 


* parameter l=label, parameter 2=’n' 
factor MACRO 

IFND \1 

\1 set 1 set if not yet defined 


ENOC 

IFGT \2 
factor \1,\2-1 
\1 set \1*(\2) 

ENDC 
ENDM 

* a sample call 

factor test,3 


work out next level down 
n=n*factor(n-1) 
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The net result of the previous code Is to set test to 31 (3 factorial). 
The reason the second SET has (\2) Instead of just \2 Is that the 
parameter will not normally be Just a simple expression, but a list 
of numbers separated by minus signs, so It could assemble to 


(l.e. test *5-3) instead of the correct 
test set test* <5—1—1—1) 

(i.e. test *2). 

Example 4 - Conditional Return Instruction 

The 68000 lacks the conditional return Instructions found on 
other processors, but macros can be defined to implement them 
using the \@ parameter. For example, a return If EQ macro could look 
like: 

rtseq MACRO 



ENDM 


The \@ parameter has been used to generate a unique label every 
time the macro is called, so will generate in this case labels such as 
_002 and_0i7. 

Example 5 - Numeric Substitution 

Suppose you have a constant containing the version number of 
your program and wish this to appear as ASCII In a message: 

showname MACRO 

dc.b \1,'\<version>',0 
ENDM 


showname <'Real Ale Search Program v’> 
will expand to the line 

dc.b 'Real Ale Search Program v','42',0 
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Note the way the string parameter is enclosed in <>s as it contains 
spaces. 

Example 6 - Complex Macro Call 

Suppose you program needs a complicated table structure which 
can have a vaiying number of fields. A macro can be written to only 
use those parameters that arc specified, for example: 


table_entry 

dc.b 
XFNC 
dc.w 
ENDC 
dc. 1 
IFNC 
dc.b 
ENDC 
dc.b 

•end\@ dc.b 
ENDM 

* sample call 

eable_en£ry $42,,,t1,t2,t3,t4, 

4 " <Enter name:>,%0110 

This is a non-trlvial example of how macros can make a 
programmer's life so much easier when dealing with complex data 
structures. In this case the table consists of a length byte, 
calculated in the macro using two optional words, four longs, 
an optional string, a byte, then a zero byte. The code produced in 
this example would be 


\2,\3 

\4,\5,\6,\7 


1 3rd together 


.end_001 


dc.b 

dc.b 


dc.l 



.end 001 

$42 

tl, t2, t3,t4 
•Enter name:' 
%0100 
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Output File Formats 


GenST Is very flexible In terms of output file formats. These are 
detailed In this section together with notes on the advantages and 
disadvantages of each. Certain directives take different actions, 
depending on what output file format Is specified. 

The exact details of using each format will now be described. 

Executable Flies _ 

These are directly executable, for example by double-clicking from 
the Desktop. The file may include relocation Information and/or 
symbolic information. Normal file extensions for this type file are 
.PRG, .TOS, .TTPand .ACC. 

Advantages true BSS sections, reduced development time. 
Disadvantages messy if more programmer. 

GST Linkable Files _ __ _ 


When writing larger programs, or when writing assembly 
language modules for use from the high-level language, a 
programmer needs to generate a linkable file. The GST linker 
format is supported by the majority of high-level languages 
produced In England as well as others, for example HiSoft BASIC. 
Lattice C, Prospero FORTRAN and Prospero Pascal. GST format 
files normally have the extension of . bin. 

Advantages great degree of freedom - Imported labels can be 
used practically anywhere Including within arbitrary expressions, 
libraries can be created directly from the assembler. Import 
method means assembler can detect type conflicts. 

Disadvantages library format means selective library linking can 
be slow, true GEMDOS sections not supported as standard 
(though UnkST can create true BSS sections). 
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DRIUnfcabS® gte* 




This is the original linker format for the Atari ST created by Digital 
ResetW'cb ftrigtaaMy for CP/M 68K. It is supported, often via a 
conversion utility. by the majority of US high-level languages. DRI 
format.-files-normally have the extension of .o. 

Advantages selective libraries are faster l«f link than GST 
format. GEMDOS sections fully supported. 


Disadvantages very restrictive on use of imported labels; object 
files twice as big as executable files. 8 character limit on symbols. 

Choosing the Right File Format _ 

If you wish to link with a high-level language there Isn't usually 
much choice - you have to use whichever format Is supported by 
the language. 




If you are writing entirely In assembly language then the normal 
choice has to be executable - It Is fast to assemble, no linking 
required, and allows assemble to memory for decreased 
development time. 


If you are writing a larger program, say bigger than 32k object, or 
writing a program as a team, then linkable code often makes most 
sense. We recommend GST-llnkable over DRI because of the much 
greater flexibility In the format. 


Output File Directives _ 

This section details those directives whose actions depend on the 
output file format chosen. The file format itself can be chosen by 
one of the following methods; command line options using 
GENST2 .ttp; clicking on the radio buttons In the Assembly Options 
dialog box from the editor; or with the opt L directive at the 
beginning of the source file. 
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Icons are vised to denote those sections specific to a file format, viz: 


E&scutable-code, also asscmbled-to-mcmory code 


GST-llnkable code 


DRI-llnkable code 




Modules & Sections 


MODULE moMMame 

This defines the start of a new module. The module name should be 
contained within quotes If spaces arc Included in It. There is a 
default module called anon module so the directive is not obligatory. 


This directive is Ignored. 


Em 


This directive Is ignored. 


This directive allows assembly-language libraiy files to 
be created using multiple modules. Each module is like a self- 
contained program segment, with Its own imports and exports. 
Relative labels are local to their own module, so you can use two 
IjSete-with the same name In different modules with no dangsr of a 
®s&te. Absolute labels arc global to all modules, ideal fae convtsstfte 
■SP;?’fse like. 
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SECTION sectlonname 

This defines a switch to the named section. A program may consist 
of several sections which will be concatenated together with other 
sections of the same name In the final executable file. By default 
assembly starts In the TEXT section. You may switch to any section 
at any time during an assembly. 


Allowed section names are TEXT, the normal program 
W area. DATA, for Initialised data, and BSS, a special area of memory 
reserved by the GEMDOS program loaded. It Is Initialised to zeroes 
and takes up no space within the disk file. When in a BSS section no 
code-generating Instructions are allowed except the DS directive. 
Using a BSS section for global variables can save valuable disk 
space. 


The rules described above for executable flies apply. 


There are no rigid rules about section names. Sections 
with the same name from different files will be concatenated by the 
linker. The default ordering of sections is the order they are first 
used In. 


Imports & Exports 


With both linkable types of program It is crucial to be able to Import 
, and export symbols, both relative symbols (l.e. program 
references) and absolute symbols (l.e. constants). The GST format 
distinguishes between these types whereas the DRI format does 
not. The GST format allows the assembler to type check, often 
finding programming errors that would otherwise be missed. 
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XDEF exportc,export>„. 

This defines labels for export to other programs (or modules). If 
any of the labels specified are not defined an error will occur. It is 
not possible to export local labels. 


This directive is Ignored. 


XREF import<,lmport)>... 

XREF.L import<,lmport>... 

This defines labels to be Imported from other programs or 
modules. If any of the labels specified are defined an error will 
occur. The normal XREF statement should be used to Import a 
relative label (l.e. program reference), while XREF.L should be used to 
Import absolute labels (i.e. constants). Importing a label more than 
once will not produce an error. 


This directive is ignored. 


The DRI format does not actually need to know the 
type of imports but it Is recommended that both forms of XREF are 
used to allow the assembler to type check. If you do not type your 
imports you should turn type-checking off using opt t-. DRI 
labels are only significant to the first 8 characters. 
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Using Imports In Expressions 


imports! 


Imports may be used in expressions but only one 
import per expression is allowed. The result of an expression with 
an Import in must be of the form Import+number or Import-number. 
Imports can be combined with arbitrarily complex expressions, so 
long as the complex expression lexically precedes it, for example 

move. 1 3+<l«count+5)+import 


Imports may be used in expressions, with up to ten 
per expression. They may only be added or subtracted from each 
other though can be combined with arbitrarily complex 
expressions, so long as the complex expression lexically precedes 
it, for example: 


move .1 3+ (l«count+5) +import 1-import 2 

Where exactly an expression involving an import can be used 
depends on the file format. The following table shows which are 
allowed. 


Expression GST DM 

PC-byte Y N 

>w PC-word Y Yf 


byte Y N 

word Y Y 

long Y Y 


Example 

move.w import(pc,d3.w) 
bsr.s import 
move.w import(pc),a0 
bsr import 
move.b #import,dO 
move.w import(a3),d0 
move.l import,dO 


tso long as it is not a reference to a different section in the same 
program, which is not allowed. 


Note that a reference to a symbol in a 
different section is regarded as an import and subject to the above 
rules. 
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COMMENT commentstring 


This directive is Ignored. 


This directive is Ignored. 


This directive passes the following string, exactly as 
entered. Into the . bin file and will be shown by the linker. 


Si J 


ORG expression 

This will make the assembler generate position-dependent code 
and set the program counter to the given value. Normal GEMDOS 
programs do not need an ORG statement even if position- 
dependent. It is included to allow code to be generated for the ROM 
port or for other 68000 machines. More than one ORG statement 
is allowed In a source file but no padding of the file is done. 


It should be used with great care as the binary file 
generated will probably not execute correctly when double-clicked, 
as no relocation information is written out. The binary file 
produced has the standard GEMDOS header at the front, but no 
relocation information. 


This directive is not allowed, absolute code generation sj 
option in the linker. 


This sends the ORG directive to the linker which will 
pad the file with zeroes to the given address. 


This directive is very unlikely to make sense when 
to memory. 
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OFFSET <expression> 


This switches code generation to a special secUon to generate 
absolute labels. The optional expression sets the program counter 
for the start of this section. No bytes are written to the disk and 
the only code-generating directive allowed is DS. Labels defined in 
this section will be absolute. For example to define some of the 
system variables of the ST: 


OFFSET $400 


etv_t inter ds.l 
etv_critic ds.1 
etv~term ds.1 
ext_extra ds.l 
memvalid ds.l 
memcntlr ds.w 


_LK (reserved symbol) 


This is a reserved symbol that can be used to detect which output 
mode is specified The value of this symbol is always absolute and 
one of the following: 


0 executable 

1 GST linkable 

2 DRI linkable 


Other values are reserved for future expansion. 

DRI Debug Option _ 

Normally only explicitly XDEFed labels are Included in the symbol 
r table within the output file. However the format allows what it calls 
w local labels (not to be confused with GenST local labels) which are 
not true exports and cannot be referred to in other modules but 
will be Included in the symbol table in the final output file for 
debugging purposes, opt d+ will cause all relative labels to be 
output as DRI local labels. 

Writing GST libraries ___ 

When using multiple MODULES to generate a GST format library 
file care must be taken with backward references to imports. 
Within a library file, higher level routines should be first, lower level 
routines last. For example the source file skeleton overleaf not link 
when used as a selective library. 
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MODULE 


low_level 
XDEF low_OUtput 

low_output 

etc 

MODULE high_level 

XDEF high_output 

XREF low_output 

high_output 
etc 


This Is because the second module references a label defined In an 
earlier module, which Is not allowed. The corrected version Is: 


MODULE high_level 
XDEF high_output 

XREF low_output 

high_output 


MODULE 

XDEF 

low_output 


low_level 

low_output 




Simple File Format Examples __ 

This section shows a (non-functional and incomplete) example of 
the use of each file format. 


SECTION 
start lea 

«ove.l 

bar 

bra 

SECTION 

dc.b 

SECTION 

printstring 

trap 

addq.l 


TEXT 

string(pc) ,a0 

aO,save_str 

printstring 

quit 

DATA 

•Enter your name,0 
TEXT 

aO, -(sp) 

#9, -(sp) 

II 

16, sp 




Assembler 


HiSoft DevpacST 



DRI Linkable 




XREF.L 

SECTION 

start move.1 

move.1 
bsr 
bra 

SECTION 
string dc.b 

SECTION 

printstring 


trap 
addq.1 


quit 

#string,aO 
aO,save_str 
printstring 
quit 
DATA 

'Enter your name,0 
TEXT 

aO,-(sp) 

#9, -(sp) 

SI 

#6, sp 


Note the way the first instruction has been changed as a PC- 
relative reference is not allowed between sections. 


GST Linkable 


MODULE TESTPROG 
COMMENT needs work 
XREF.L quit 
SECTION TEXT 
lea string(pc),a0 
move.1 aO,save_str 
bsr printstring 
bra quit 
SECTION DATA 
dc.b 'Enter your nan 
SECTION TEXT 
ring 

move. 1 aO,-(sp) 


SECTION BSS 
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Directive Summary 


Assembly Control 

END terminate source code 

INCLUDE read source file from disk 

INCBIN read binary file from disk 

OPT option control 

EVEN ensure PC even 

CNOP align PC arbitrarily 

DC deflne constant 

DS define space 

DCB define constant block 

FAIL force assembly error 

Repeat Loops 

REPT start repeat block 

ENDR end repeat block 


Listing Control 

LIST enable listing 

NOLIST disable listing 

PLEN set page length 

LLEN set line length 

TTL set title 

SUBTTL set sub-title 

PAGE start new page 

LISTCHAR send control character 

FORMAT deflne listing format 

Label Directives 


EQU deflne label value 

EQUR deflne register equate 

SET deflne label value temporarily 

REG deflne register list 

RS reserve space 

RSRESET reset RS counter 

RSSET set RS counter 
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Conditional Assembly 


IFEQ assemble If zero 

IFNE assemble If non-zero 

IFGT assemble If greater than 

IFGE assemble If greater than or equal to 

IFLT assemble If less than 

IFLE assemble If less than or equal to 

IFD assemble if label defined 

IFND assemble If label not defined 

IFC assemble If strings same 

IFNC assemble If strings different 

ELSEIF switch assembly state 

ENDC end conditional 

I1FC Immediate IF 

Macros 

MACRO define macro 

ENDM end macro definition 


Output File Directives 


MODULE 

SECTION 

XDEF 

XREF 

COMMENT 

ORG 

OFFSET 


start new module 
switch section 
define label for export 
define label for import 
send linker comment 
set absolute code generation 
define offset table 


Reserved Symbols 

NARG number of macro parameters 

_G2 Internal version number 

_RS RS counter 

_LK output file type 
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CHAPTER 4 
Symbolic Debugger 

Introduction_ 


Programs written In assembly language are particularly error- 
prone because even a slight mistake can result In the enUre 
machine crashing. There are various forms of bugs, ranging from 
the trivial (e.g. a missing CR In a printout), through the usual (e.g. 
an Incorrect result) to the very serious (e.g. the machine completely 
hanging, perhaps with a weird display). 

To help you find and correct all forms of bugs. DevpacST Includes 
MonST. MonST Is a symbolic debugger and disassembler which 
lets you examine programs and memory, execute programs an 
Instruction at a time and trap processor exceptions caused by 
programmer error. As MonST is symbolic you can look at your 
program complete with all the original labels, making debugging 
very much easier than having to battle with 6-dlgit hex numbers. 

Although MonST Is a low-level debugger, displaying such things as 
68000 Instructions and bytes of memory, it can also be used for 
debugging programs written with any compiler that generates 
machine-code output. If the compiler has the option to dump the 
symbols Into the binary code then you will see your procedure and 
function names within the code, and you can even view your 
original source code. We ourselves used MonST when debugging 
LinkST, which was written using a C compiler. MonST and GenST 
themselves were written entirely In assembly language. 

As MonST uses Its own screen memory, the display of your 
program is not destroyed when you single-step or breakpoint, 
making it particularly useful for graphical-output programs such 
as GEM applications or games. It also uses Its own screen drivers 
so It is possible to single-step Into the operating system screen 
routines such as the AES or BIOS without affecting the debugger. 

There are three versions of MonST supplied on the disk. All are 
similar to use and are provided to make the debugging of different 
types of progS'Kffi:® sasy. The exact differences are detailed later. 
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68000 Exceptions 


MonST uses the 68000 processor exceptions to stop runaway 
programs and to single-step, so at this point It would be useful to 
explain them and what normally happens when they occur on an 


There are various types of exception that can occur, some 
deliberately, others accidentally. When one does occur the 
processor saves some Information on the SSP, goes Into Supervisor 
mode and Jumps to an exception handler. When MonST Is active It 
re-dlrects some of these exceptions so It can take control when 
they occur. The various forms of exceptions, their usual results, 
and what happens when they occur with MonST active Is shown In 
the following table: 


Illegal Instruction bombs 
sero divide bombs 

CHK Instruction bombs 

TRAPV Instruction bombs 


bombs 

fast VDI Interface 
Internal TOS 


trapped 

(rapped 

(rapped 

trapped 

used for single-stepping 


CEMDOScaU 
AES/VDI call 
(rapped 


The exact causes of the above exceptions (and how best to recover 
from them) are detailed at the end of this section, but to 
summarise: 

Exceptions 2 to 8 are caused by a programmer error and are 
trapped by MonST. 

Exception 9 can remotely be caused by programmer error and Is 
used by MonST for single stepping. 

Exceptions 10, 11, 33. 34, 45 and 46 are used by the system and 
left alone. 
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The rest (i.e. the unused Trap exceptions) are diverted Into MonST. 
but can subsequently be re-deflned to be exploited by programs if 
required. 

The 'bombs' entry In the table above means that the ST will attempt 
to recover from the exception, but it is not always successful. 

When an exception occurs, the ST prints on the screen a number of 
bomb shapes (or mushrooms on disk-loaded GEMDOS). the 
number being equal to the exception number. Having done this, it 
will abort the current program (losing any unsaved data from It) 
and attempt a return to the Desktop. 

If the exception was caused by or resulted In important system 
variables being destroyed then the attempt may fail and the 
machine will not recover. 

Occasionally very nasty crashes can cause the whole screen to fill 
with bombs (or mushrooms) which looks very impressive, but Is 
not very useful! 

Memory Layout _ 

The usual versions of MonST co-reside with programs being 
debugged; that Is. they are loaded, ask for a filename, and load that 
file In together with any labels. 

It is useful to examine the usual logical memory map (the physical 
layout Is shown in Appendix C) both with and without MonST. 
shown In Figure 4.1 on the next page. 
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Without MonST 


With MonST 


Figure 4.1 - Logical Memory Map 

The actual code size of MonST is around 23k. but In addition it 
requires an additional 32k of workspace. This may seem large but 
it is required for the copy of the ST screen memory saved by 
MonST: this is a most useful feature of the debugger. 

The three versions of MonST supplied are: 

MONST2. prg GEM interactive version 
monst 2 . tos TOS interactive version 
amonst2.prg Auto-resident version 

For now the first two will be described: the auto-resident version is 
described later but is very similar in use to the others. 
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Invoking MonST 

From the Desktop 


The two Interactive versions of MonST are actually Identical except 
for the filename extension. The GEM version should be used for 
GEM-based programs, which require use of the mouse and have 
initially a grey-pattem screen, while the TOS version should be 
used for TOS-bascd programs which require the flashing TOS 
cursor and have Initially a white screen display. Both versions are 
invoked by double-clicking on their respective Icons from the 
Desktop. 


If you debug a TOS program with the GEM version of 
the debugger It will work fine but the screen display will be probably 
be messy; however, debugging a GEM program with a TOS 
debugger will cause all sorts of nasty problems to occur and should 
be avoided. 


From the Editor 


When GenST Is Invoked it automatically looks for and loads the flic 
MONST2.PRG Into memory (unless this option is disabled In the 
Preferences option In the editor). The debugger is then instantly 
available at the press of a key from within the editor. 

Pressing Alt-M or clicking on MonST from the Program menu will 
then Invoke It in a similar way to that described above for the disk- 
based version only very much more quickly. 

Pressing Ait-D or clicking on Debug from the Program menu will 
Invoke MonST but will also automatically prepare a program 
previously assembled to memory to be run. Including any symbols 
within It. 

The type of Initial screen mode used when Invoked from the editor 
is determined by the Run with GEM menu item on the Program 
menu - If a check mark is present then GEM screen Initialisation is 
done, otherwise TOS screen initialisation is used. The rules 
described above about using the wrong type of screen initialisation 
are also relevant to the in-memory debugger. 
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Symbolic Debugging _ 

A major feature of MonST is its ability to use symbols taken from 
the original program whilst debugging. MonST supports two 
formats for debug information - the DR] standard, which allows up 
to 8 characters per symbol, and the HiSoJt Extended Debug 
format, allowing up to 22 characters. Both GenST and LinkST can 
produce both formats, and many other vendors' compilers and 
linkers have an option to produce DRI-format debugging 
information. We arc trying to establish the HiSoft Extended format ) 
as a second standard on the ST. but at the time of writing the only 
other products to support the format are HiSoft BASIC and FTL- 
Modula 2. 

MonST Dialog and A im Boxes _ 

MonST makes extensive use of dialog- arief alert-boxes which are 
similar In concept to those in GEM programs but have several 
differences. MonST does not use genuine GEM-typc boxes in order 
for it to remain robust - that Is to avoid interaction when 
debugging programs that themselves use GEM calls. In addition 
the mouse is not available within the debugger Itself which makes 
things like true GEM buttons impossible. 

A MonST dialog box displays the prompt ESC to abort abow.fe 
top left comer of the box together with a prompt, normally fe$*5Bjfc& 
by a blank line with a cursor. At any time a dialog box M 
aborted by pressing Esc, or data may be entered by typing. The 
cursor keys. Backspace and Del keys may be used to edit entered 
text in the usual way and the whole line may be deleted by pressing 
the cir key - note that this is different to GEM dialog boxes which w' 
use the Esc key to delete a whole line of text. An entered line is 
terminated by pressing the Return key. though If the line contains 
errors the screen will flash and the Return key will be ignored 
allowing correction of the data before pressing Return again. 
Another difference is that dialog boxes that require more than one 
line of data to be entered do not allow the use of the cursor up and 
down keys to switch between different lines - In MonST the lines 
have to be entered in order. 
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A MonST alert box Is a small box displaying a message together 
with the prompt (Return) and is normally used to Inform the user 
of some form of error. The box will disappear on pressing the 
Return or Esc keys, whichever Is more convenient. 

Initial Display _ 

Unless you have chosen the Debug option within the editor you 
will be presented with a dialog box prompting for an executable 
program name. If you wish to debug a program from disk you 
should enter the filename (which defaults to an extension of .prg) 
then press Return, then you wfil be prompted for any command 
line. If you do not wish to debug a program from disk at this stage, 
for example you wish to investigate memory, press the Esc key or 
enter a blank filename. 


J Certain features work differently or are not available 
when using MonST In low resolution. They are shown with this 


Front Panel Display 


The main display of MonST is via a Front Panel showing registers, 
memory and instructions. The name Front Panel stems from the 
type of panels that were mounted on mainframe and mini 
computers to provide Information on the state of the machine at a 
particular moment, usually through the use of flashing lights. 
These lights represent whether or not particular flip-flops 
(electronic switches) within the computer are open or closed; the 
flip-flops that are chosen to be shown on this panel are normally 
those that make up the Internal registers and flags of the 
computer thus enabling programmers and engineers to observe 
what the computer is doing when running a program. 

So these are hardware front panel displays; what MonST provides 
you with is a software front panel - the code within MonST works 
out the state of your computer and then displays this Information 
on the screen. 
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The JiSHaJ. MftaST Jfisplay consists of four windows, similar to 
those eiajwa 4.1. In low-resolution the arrangement of 

two of ?ise slightly different to allow efficient use of the 

smaller ©taSa&is ssfsen space. 



Figure 4.1 MonST Initial Display 


w 1 


The top window (number 1) displays the values of the data and 
address registers, together with the memory pointed to by these 
registers. 


The next window (number 2) is the disassembly window, this 
displays several lines of instructions, by default based around the 
program counter (PC), shown in the title area of the window. A =» 
sign Is used to denote the current value of the PC. 

Window number 3 Is the memory window which displays a section 
of memory In word-aligned hex and ASCII. 


The Saal window the bottom of the screen, which is un¬ 
numbered, (is the smallest window and is used to display 
messages-. 

One of the tiost powerful features of MonST is its flexibility with 
windows • to 2 additional windows may be created, the font size 
can be changed, and windows may be locked to particular 
najfcsta'S, these features are detailed later. 
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S mple Window Handling _ 

has the concept of a current window - this Is denoted by 
f?i3ti"aylng Its title In black. The current window may be changed by 
pMig the Tab key to cycle between them, or by pressing the Alt 
together with the window number, for example Alt-2 selects 
thfi disassembly window. (AZERTY keyboard users please note - 
the Shift key Is not required when using Alt to select windows). 
Note that the lowest window can never be made the current 
window - It Is used solely for displaying messages. 

Command Input _ 


MonST Is controlled by single-key commands which creates a veiy 
fast user-interface, though this can take getting used to If you are 
familiar with a llne-orlented command Interface of another 
debugger. Users of HISoft Devpac on other machines will Sod many 
commands are identical, particularly with the SpecfeTiaf and QL 
debuggers, though the window commands are unique itiSfonST. 

In general the Alt key Is the window key - when used In 
conjunction with other keys It acts on the current window. 

Commands may be entered In either upper or lower case. Those 
commands whose effects are potentially disastrous require the 
Ctrl key to be pressed In addition to a command key. The keys 
used were chosen to be easy to remember, wherever possible. 
Commands take effect Immediately - there Is no need to press 
Return and Invalid commands are simply Ignored. The relevant 
sections of the front panel display are updated after each 
command so any effects can be seen Immediately. 

MonST is a powerful and sometimes complex program and we 
realise that It is unlikely that many users will use every single 
command. For this reason the remainder of the MonST manual Is 
divided Into two sections - the former Is an introduction to the 
basic commands of the program, while the latter Is a full reference 
section. It Is possible for new users and beginners to use the 
debugger effectively while having only read the Overview; don't be 
intimidated by the Reference section. 
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MonST Overview 


To start with you will need to load a program to debug: If you have 
assembled a program to memory you can use the Debug option 
from the editor, else you will need to load a program from disk. 

When initially loaded you will be prompted for a filename. If you got 
an error or didn't specify a filename you can have another go by 
pressing ctrl-L. 

A program's symbols will be used by the debugger. If found. A 
program will have symbols Included If you used the Debug or 
Extended Debug options of the assembler. The extended debug 
option means you will get longer symbols, the normal option 
forces them to be truncated to 8 characters. 

The most common command In MonST Is probably single-step, 
obtained by pressing ctrl-z (or ctn-Y If you find It more 
convenient). This will execute the Instruction at the PC. the one 
shown In the Register window and. normally, also In the 
Disassembly window. After executing It the debugger re-dlsplays 
the values of the registers and memory displayed, so you can 
watch the processor execute your program, step by step. Single¬ 
stepping Is the best way of going through sections of code that are 
suspect and require deeper Investigation, but It Is also the slowest - 
you may only be Interested In a section of code near the end of your 
program which could take ages to get to If you have to single-step 
all the way. There Is. of course, an answer. 

A breakpoint Is a special word placed into your program to stop It 
running and enter MonST. There are many types of breakpoint but 
we will restrict ourselves to the simplest for now. A breakpoint may *^) 
be set by pressing Ait-B. then entering the address you wish to 
place the breakpoint. You can enter addresses in MonST In hex 
(the default base), as a symbol, or as a complex expression. 
Examples of valid addresses are 1A2B0. prog sfc«*e, 10+mydata. If 
you type In an Invalid address the screen will Bash and allow you to 
correct the expression. 

Having set a breakpoint you need some way of letting your 
program actually run. and ctri-R will do this. If will execute your 
program using the registers displayed and starting from the PC. 
MonST will be re-entered If a breakpoint has bees h!fc sr if suj 
exception occurs. 
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MonST uses its own screen display which is independent from 
your programs. If you press the v key you will see your cun-ent 
programs display, pressing another key switches you back to 
MonST. This allows you to debug programs without disturbing 
their output at all. 

MonST uses its own windows to. and any window may be zoomed 
to the full screen size by pressing Alt-z. To return to the main 
display press Alt-z or the Esc key. The esc key is also the best way 
of getting out of anything you may have invoked by accident. The 
Zoom command, like all Alt-commands, works on the current 
uindow which you can change by pressing Tab. You can dump the 
«S?$nt window to your printer by pressing Ait-P. 

'S': ehange the address from which a window displays it data, press 
Ait-A, then enter the new address. Note that the disassembly 
window will always re-display from the PC after you single-step, 
because it is locked to the PC. The locking of windows is detailed in 
the Reference section. 

To quit MonST press Ctrl-C. Strange as It may sound this will not 
always work - what Ctrl-C does is terminate the current program, 
which may be MonST or more likely, the program you are 
debugging. You know when you have terminated the program 
under investigation bsceusc it will say so In the lower window. Once 
your program has been terminated, pressing ctrl-c will terminate 
MonST. If you used the Debug option from the editor then Ctrl-C 
will always terminate MonST as well as your program. 

We hope this overview has given you a good Idea of the most 
common features of MonST to let you get on with the complex 
process of writing and debugging assembly language programs. 
When you feel more confident you should try and read the 
Reference section, probably best taken, like all medicine, in small 
doses. 
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MonST Reference 


Numeric Expressions 


MonST has a lull expression evaluator, based on that In GenST, 
Including operator precedence. The main differences are that the 
default base Is hexadecimal (decimal may be denoted with a \ sign), 
there Is no concept of types of expressions (relative or absolute). * j 
Is used only for multiplication and there Is a not-cquals operator. 


Symbols may be referred to and are normally case-sensitive and 
significant to either 8 or 22 characters (depending on the form of 
debug used), though this can be changed with Preferences. 

Registers may be referred to simply by name, such as A3 or D7 
(case Insensitive), but this clashes with hex numbers. To obtain 
such hex numbers precede them with either a leading zero or a $ 
sign. A7 refers to the user stack pointer. 

There are several reserved symbols wisiwb are esse insensitive, 
namely text, data, bss. end. sp. sr. and. ssr. Etfo refers to one byte 
past the end of the BSS section and s» rear.;.-# to cither the user- or 
supervisor-stack, depending on the current value of the status 
register. 

In addition there are 10 memories numbered MO through M9. which 
are treated In a similar way to registers and can be assigned to 
using the Register Set command. Memories 2 through 5 Inclusive 
refer to the current start address of the relevant window and 
assigning to them will change the start address of that window. 

The MonST expression evaluator also supports Indirection using 
the ( and ) symbols. Indirection may be performed on a byte, word 
or long basis, by following the ) with a period then the required 
size, which defaults to long. If the pointer Is Invalid, either because 
the memory is unreadable or even (If word or Iongword Indirection 
Is used) then the expression wiS not be valid. 


Page 90 


Debugger 


HiSoft DevpacST 




For example, the expression 
idata_start+ 10 ).w 

will return the word contents of location data_start+iO, assuming 
data_start is even. Indirection may be nested in a similar way to 
ordinary parenthesis. 

Window Types _ 

l 'w There are four window types and the exact contents of these 
windows and how they are displayed is detailed below. The allowed 
types of windows Is shown in the table below. 

Window Allowed Types 

1 Register 

2 Disassembly 

3 Memory 

4 Disassembly. Memory or Source-code 

5 Memory 

Register Window Display ___ 

The data registers are shown in hex. together with the ASCII 
display of their low byte and then a hex display of the eight bytes 
they point to in memory. The address registers are also shown in 
hex, together with a hex display of 12 bytes. As with all hex 
displays in MonST this is word-aligned, with non-readable 
memory displayed as **. 

The status register is shown in hex and Ik Sfe-Jg fijrm, additionally 
with u or s denoting user- or supervisor-i&dt&s-i.'A7 1 denotes the 
supervisor stack pointer, displayed in a similar way to the other 
address registers. 

The PC value is shown together with a disassembly of the current 
instruction. Where this involves one or more effective addresses 
these are shown in hex. together with a suitably-sized display of 
the memory they point to. 
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For example, the display 


TST.S 51tfft(A3) ;00001FAE 0F01 

signifies that the value of S12A plus register A3 Is sifae. and that 
the word memory pointed to by this Is S0F01. A more complex 
example is the display 


MOVE.W $12A(A3),-)iS« 1 <OOC‘Olr,\£ QfJi «*|0fl2AC08 FFFF 

The source addressing moie 4 asi heir® !».it the destination 
address Is S2AC08. presecM imtaSiTSng $es&t. Wote that this 
display Is always of a suhflfck- 'tfi fyovai data bltkij displayed as a 
quad-word) and when pie-msratlieili adffi&»Uig'S3 used this is 
included In the address calculation#.’ 


I ***" 1 ""* ' hex dattj'/i af-trwi: for the Masters a 
address register data area is' to 4 £;»%*.'; Ba addition the 

disassembly line may mi be tecsg enotvgtt'^ Replay complex 
addressing modes such ap p§ ^ 


Disassembly Window Display 


Disassembly windows display memory as disassembled 
Instructions to the standard described below. On the left the hex 
address is shown, followed by any symbol, then the disassembly 
Itself. The current value of the PC Is denoted with =». 

If the instruction has a breakpoint placed on It this Is shown using 
square brackets (( )) afterwards, the contents of which depend on 
the type of breakpoint. For stop breakpoints this will be the j 
number of times left for this instruction to execute, for conditional 
breakpoints this will be a ? followed by the beginning of the 
conditional expression, for count breakpoints this will be a = sign 
followed by the current count, and for permanent breakpoints a * 
is shown. 
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The exact format of the disassembled op-codes Is Motorola 
standard, as GenST accepts. All output Is upper-case (except 
lower-case labels) and all numeric output Is hex. except Trap 
numbers. Leading zeroes are suppressed and the S hex delimiter Is 
not shown on numbers less than 10. Where relevant numerics are 
shown signed. The only deviation from Motorola standard Is the 
register lists shown In movek instructions - In order to save display 
space the type of the second register In a range Is abbreviated, for 
example 


MOVEM.L dO-d3/aO-a2,-(sp) 
will be disassembled as 

MOVEM.L dO-3/aO-2,-(sp) 


Any displayed symbols replace the hex address 


display, limited to a maximum of 8 characters. 


Memory Window Display 


Memory windows display memory In the form of a hex address, 
word-aligned hex display and ASCII. Unreadable memory locations 
are denoted by •*. The number of bytes shown Is calculated from 
the window width, up to a maximum of 16 bytes per line. 


Source-code Window Display 


The source-code window displays ASCII files In a similar way to a 
screen editor. The default tab setting is 8 though this can be 
toggled to 4 with the Edit Window command. 

Window Commands_ 


The Alt key is generally used for controlling windows, and when 
used apply to the current window. This Is denoted by having an 
inverse title and can be changed by pressing Tab or Alt plus the 
window number. 

Most window commands work In any window, zoomed or not. 
though when It does not make sense to do something the 
command is Ignored. 
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Alt-A 


Set Address 


This sets the starting address of a memory or disassembly 
window. 

Alt-B _ Set Breakpoint 

Allows the setting of any type of breakpoint, described later under 

Breakpoints. 

Alt-E _Edit Window 


On a memory window this lets you edit memory In hex or ASCII. 
Hex editing can be accomplished using keys 1-9. a-f, together with 
the cursor keys. Pressing Tab switches between hex & ASCII. ASCII 
editing takes each keypress and writes it to memory. The cursor 
keys can be used to move about memory. To leave edit mode press 
the Esc key. 

On a register window this Is the same as Alt-R, Register Set, 
described shortly. 

On a source-code window this toggles the tab setting between 4 
and 8. 


Alt-F 


Font size 


This changes the font size In a window. In high resolution 16 and 8 
pixel high fonts are used. In colour 8 and 6 pixel high fonts are 
used. This allows a greater number of lines to be displayed, 
assuming your monitor can cope. 

Changing the font size on the register window causes the position 
of windows 2 and 3 to be re-calculated to fill the available space. 

Alt-L_Lock Window 


This allows disassembly and register windows to be locked to a 
particular register. After any exception the start address of the 
window Is re-calculated, depending on the locked register. 
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To unlock simply enter a blank string. By default window 2 Is 
locked to the PC. You can lock windows to each other by specifying 
a lock to a raemoiy window, such as M2. 

Alt-O_ Show Other 


This prompts for an expression and displays It In hex. decimal and 
as a symbol If relevant. 

Alt-P _ Printer Dump 

Dumps the current window contents onto the printer. It can be 
aborted by pressing Esc. 

Alt-R_ Register Set 


Allows any register to be set to a value, by specifying the register, 
an equals sign, then its new value. It can also be used to set the 
value of memories. For example the line 

a3=a2+4 

sets register A3 to be A2 plus 4. You can also use this to set the start 
address of windows when In zoom mode so that on exit from zoom 
mode the relevant window starts at the required address. 


IIUIiM 


Do not assign to M 


if window 4 Is currently a source- 


Alt-S 


Split windows 


This either splits window 2 Into 2 and 4, or splits window 3 Into 3 
and 5. Each new window Is Independent from Its creator. Pressing 
Alt-s again will unspllt the window. 


This command has no effect. 
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Alt-T 


Change Type 


This only works on window 4 (created either by splitting window 2 
or by loading a source file). It changes the type of the window 
between disassembly, memory and source-code (if a file has been 
loaded). 

Alt-Z_Zoom Window 


This zooms the cun-ent window to be full size. Other Alt 
commands are still available and normal size can be achieved by 
pressing Esc or Ait-z again. 


IBM 


Zooming the register window Is unlikely to be useful. 


Cursor Keys 


The cursor keys can be used on the current window, the action of 
which depends on the window type. 

On a memory window all four cursor keys change the current 
address, and Shift t and shift 1 move a page In either direction. 

On a disassembly window T and i change the start address on an 
Instruction basis. «- and -» change the address on a word basis. 

On a source-code window t and i change the display on a line 
basis, and Shift T and shift l on a page basis. 

Screen Switching _ 

MonST uses its own screen display and drivers to prevent 
interference with a program's own screen output. To prevent 
flicker caused by excessive screen switching when single-stepping 
the screen display is only switched to the program's after 20 
milliseconds, producing a flicker-free display while In the debugger. 
In addition the debugger display can have a different screen 
resolution to your program's if using a colour monitor. 
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V 


View Other Screen 


This flips the screen to that of the programs, any key returns to 
the MonST display. 

Ctrl-O_Other Screen Mode 


This changes the screen mode of MonSTs display between low and 
medium resolution. It re-initiallses window font sizes and 
L, positions to the Initial display. This will not effect the screen mode 
of the program being debugged. 


This command is ignored on a monochrome monitor. 


As MonST has its own idea of where the screen Is. what mode it is 
in and what palettes to use you can use MonST to actually look at 
the screen memory in use by your program, ideal for low-level 
graphics programs. 


If your program changes screen position or 
resolution, via the XBIOS or the hardware registers, it is important 
that you temporarily disable screen switching using Preferences 
while executing such code else MonST will not notice the new 
attributes of your program's screen. 




When a disk is accessed, when loading or saving, the screen 
display will probably switch to the program’s during the operation. 
This is in case a disk error occurs, such as write-protected or read 
errors, as it allows any GEM alert boxes to be seen and acted upon. 
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Breaking into Programs 


Shift-Alt-Help _ Interrupt Program 

While a program Is running It can be Interrupted by pressing this 
key combination, which will cause a trace exception at the current 
value of the PC. With computatlonally-intense program sections 
this will be within the program Itself but with a program making 
extensive use of the ROM. such as the BDOS or AES. the 
Interruption will normally be In the ROM Itself, or the llne-F 
handler stored In low-memory. If this Is the case it Is 
recommended that a breakpoint be placed In your actual program 
area then a Return to Program command (ctrl-R) Issued. 

Pressing Alt-Help without the Shift key will normally produce a 
screen dump to the printer - If you press this accidentally It should 
be pressed again to cancel the dump. 

It Is possible for this key combination to be Ignored when pressed - 
If this occurs press It again when It should work. Pressing It when 
In MonST itself will produce no effect. 


A program should never be terminated (using ctrl-c) 
If it has Just been Interrupted In the middle of a ROM routine. This 
is likely to cause a system crash. 

Breakpoints _ 


Breakpoints allow you to stop the execution of your program at 
specified points within It. MonST allows up to eight simultaneous 
breakpoints, each of which may be one of five types. When a 
breakpoint Is hit MonST is entered and then decides whether or 
not to halt execution of your program, entering the front panel 
display, or continue; this decision is based on the type of the 
breakpoint and the state of your program's variables. 

Simple Breokpolnts _ 

These are one-off breakpoints which, when executed, are cleared 
and cause MonST to be entered. 
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Stop Breakpoints _ 

These are breakpoints that cause program execution to stop after a 
particular Instruction has been executed a particular number of 
times. In fact a simple breakpoint Is really a stop breakpoint with a 
count of one. 

Count Breakpoints _ . . 

Merely counters: each time a&jh' 6 breakpoint Is reafeJflpC* 

associated with It Is Increment^, ihd the program 

Permanent Breakpoints _ _ 

These are similar to simple breakpoints except that iffew actix 

cleared - every time execution reaches a permanent W'K&kf'otGf 

MonST will be entered. 

Conditional Breakpoints __ _ . , ,, _ __ 

The most powerful type of breakpoint and these aBo*-.pregfaia 
execution to stop at a particular address only If an arbitrarily 
complex set of conditions apply. Each conditional breakpoint has 
associated with It an expression (conforming to the rules already 
described). Every time the breakpoint Is reached this expression Is 
evaluated, and If It Is non-zero (l.e. true) then the program will be 
stopped, otherwise It will resume. 

Alt-B_ Set Breakpoint 


This Is a window command allowing the setting or clearing of 
breakpoints at any time. The line entered should be one of the 
following forms, depending on the type of breakpoint required: 

<address> 

will set a simple breakpoint. 

<address>,<expresslon> 

will set a stop breakpoint at the given address, after It has executed 
<expression> times. 
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<address>,= 


will set a count breakpoint. The Initial value of the count will be zero. 
<address>,* 

will set a permanent breakpoint. 

<address>,?<expression> 

will set a conditional breakpoint, using the given expression. 
<address>,- 

wlll clear any breakpoint at the given address. 

BreakM&Sts cannot be set on addresses which arc odd or 
unrearaMfcijr In ROM, though ROM breakpoints may be emulated 
using Sfee fferi Until command. 


Every time a breakpoint Is reached, regardless of whether the 
program is interrupted or resumed, the program state Is 
remembered In the History buffer, described later. . 


Help 


Show Help and 


This displays the text, data and BSS segment ar3$fe»Bf& bjnd 
lengths, together with every current breakpoint. ASJtJfcehilMiarma 
are available within this display. 


Ctrl-B 


Included mainly for compatibility with MonST 1, thlsfsgts asS 
breakpoint at the start address of the current window; m tap# 
is a disassembly window. If a breakpoint is already fJrsiSfe. p 
will be cleared. " ' 


U 


Go Until 


This prompts for an address, at which a simple breakpoint will be 
placed then program execution resumed. 
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Ctrl-K 


Kill Breakpoints 


This clears all set breakpoints. 

Ctrl-A_ Set Breakpoint then Execute 


A command that places a simple breakpoint at the Instruction 
after that at the PC and resumes execution from the PC. This Is 
particularly for DBF-type loops If you don't want to go through the 
loop, but Just want to see the result after the loop Is over. 

Ctrl-D_ BDOS Breakpoint 


This allows a breakpoint to be set on specific BDOS calls. The 
required BDOS number should be entered, or a blank line If any 
existing BDOS breakpoint needs to be cleared. 

HigMr; _ 

MonST has a history b:\ffer U» TKftlcSl the machine status Is 
remembered for later imestigapati. - 

The most common wiey of erstsraw tote the hlstoiy buffer Is 
when you single-step, tfjt In adratlon swwy breakpoint reached 
and every exception caftsetl saitfce the state Into the 

buffer. Various forms cf hva Rub COTintond Kluc cause entries to be 
made into this buffer. 


The hlstoiy buffer hag rcoos fo& flv* entries - when It 
fills the oldest entry is to nsK?|s roam for iie newest entry. 

u 


Stiow history Buffer 


This opens a large window displaying the contents of the history 
buffer. All register values are shown including the PC as well as a 
disassembly of the next Instruction to be executed. 
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Ctrl-C _ Terminate 

This will issue a terminate trap to the current GEMDOS task. If a 
program has been loaded from within MonST it will be terminated 
and the message Program Terminated appear in the lower window. 
Another program can then be loaded, if required. 

If no program has been loaded into MonST It will Itself terminate 
when this command is used. 


If the Debug option has been used from the GcnST editor then 
MonST will terminate automatically when the program it Is 
debugging has terminated. 


Terminating some GEM programs prematurely, 
before they have closed workstations or restored window control 
properly can seriously confuse the AES and VDI. This may not be 
noticeable immediately but often causes crashes when a 
subsequent program Is executed. 


Loading & Saving 





—ji*- 


Load Executable Program 

executable filename then a command line 
id the file ready for execution. If MonST has 
— it is not possible to load another until the 
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The file to be loaded must be an executable file - attempting to load a 
non-executable file will normally result In TOS error 66 and further 
attempts to load executable flies will normally fall as GEMDOS does 
not de-allocate the memory It allocated before trying to load the 
errant file. If this occurs terminate MonST then re-execute It and 
use the Load Binary File command. 


This command Is not available In the auto-resldent 
version of MonST or In MonST Invoked using Debug from the 
editor. 


B_ Load Binary FHe 

This will prompt for a filename and optional load address 
(separated by a comma) and will then load the file where specified. 
If no load address Is given then memory will be allocated from 
GEMDOS and used, mo will be set to the start address and Ml to the 
end address. 

S_ Save Binary File 


This will prompt for a filename, a start address and an (Inclusive) 
end address. To re-save a file recently loaded with the above 
command <filename>,MO,Ml may be specified, assuming of course 
that MO and Ml have not been re-assigned. 

A _Load ASCII File 


This powerful command allows an ASCII file, normally of source 
code, to be loaded and viewed within MonST. Window 4 will be 
created If required then set up as a source-code window. Memory 
for the source code Is taken from GEMDOS so sufficient free 
memory must be available. It Is recommended that source-code be 
loaded before an executable program to ensure enough memory. 


Window 4 Is not though an ASCII file may may be 
loaded In low-res then viewed after switching to medium resolution 
using ctri-o and pressing Ait-S. Ait-T. Ait-T. 
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If an ASCII file is loaded after an executable program 
the memory used will be owned by the program Itself. n °t MonST. 
When such a program terminates, any displayed source-code 
window will be closed. The auto-resident version of the debugger 
cannot detect this so care should be taken If loading source code 
Into it. 


Executing Programs _ 

Ctrl-R _ Return to program / Run 

This runs the current program with the given register values at full 
speed and is the normal way to resume execution after entry via a 
breakpoint. 

Ctrl-Z _ Single-Step 


This single-steps the instruction at the PC with the current 
register values. Single-stepping a Trap, Llne-A or Llne-F opcode 
will, by default, be treated as a single instruction. This can be 
changed using Preferences. 

Ctrl-Y _ Single-Step 

Identical to Ctrl-z above but Included for the convenience of 
German users. 

Ctrl-T_ Interpret an Instruction (Trace) 


This Interprets the Instruction at the PC using the displayed 
register values. It is similar to Ctrl-z but skips over BSPs, JSRs. 
Traps. Llne-A and Llne-F calls, re-entering the debugger on return 
from them to save stepping all the way through the routine or trap. 
It works on Instructions in ROM or RAM. 

r__ Run (various) 

This Is a general Run command and prompts for the type of the 
Run. to be done, selected by pressing a particular key. 
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Run 


G Go 


This Is Identical to ctrl-R, Run, and resumes the program at full 
speed. 

Run _ S Slowly 

This will run the program at reduced speed, remembering every 
step In the history buffer. 

^ Run _ I Instruction __ 

This Is similar to Run Slowly but alMn a count to be entered, so 
that a particular number of instructtMja »bay be executed before 
MonST Is entered. 

Run _ U Until __ 

You will be prompted for an expression which will be evaluated after 
every Instruction. The program will then run, albeit at reduced 
speed, until the given expression evaluates to non-zero (true) when 
MonST will be entered. For example If single-stepping a dbf loop 
which used d6 In the ROM code you could say Run Until 
d6s f ££f“f f f f (waiting for the low word of d6 to be $ffff) or, 
alternatively, pc-fcsbia, or whatever. 


This should not be confused with the Until command, 
which takes an address, places a breakpoint there then resumes 
execution. 

' w With all of these commands (except Run Go) you will then be asked 
Watch Y/N? If Y Is selected then the MonST display will be shown 
after every Instruction and you can watch registers and memory 
as they change, or Interrupt execution by pressing both shift 
keys simultaneously. If N Is selected then execution will occur while 
showing your program's display and execution may be Interrupted 
by pressing Shift-Alt-Help. 
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Selecting Watch mode with screen switching turned 
off Is likely to result In a great deal of eye strain as the display will 
be flipped after each and every Instruction, particularly alarming 
with colour monitors. 


With any of these Run modes (except Go) all Information after 
every Instruction will be remembered in the history buffer. In 
addition Traps will be treated as single-instructions, unless 
changed with Preferences, though see the warnings under that 
command about tracing all the way through ROM routines. 

When a program is running with one of the above modes a couple 
of pixels near the top left of the display will flicker, to denote that 
something Is happening, as it Is possible to think the machine has 
hung when. In fact. It Is simply taking a while to Run through the 
code an Instruction at a time. 


Searching Memory _ 

G_ search memory (Get a sequence) 

This will prompt Search for B/w/L/T/I?, standing for Bytes, 
Words, Longs, Text and Instructions. 

If you select b, w or l you will then be prompted to enter the 
sequence of numbers you wish to search for. -saah separated by 
commas. MonST Is not fussy about w37"-.: >i')gnment when 
searching, so It can find longs on odd bound«R%&,-$for example. 

If you select t you may search for any given text string, which you 
will be prompted for. The search will be case-dependent. 

If you select I you can search for part or all of the mnemonic of an 
Instruction, for example If you searched for $14 (A you would find 
an Instruction like move. L D2, $14 (AO). The case of the string you 
enter Is Important (unlike MonST version 1), but you should bear 
In mind the format the disassembler produces, e.g. always use hex 
numbers, refer to A7 rather than sp and so on. 

Having selected the search type and parameters, the search 
begins, control passing to the Next command, described below. 
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N 


find Next 


This can be used after the G command to find subsequent 
occurrences of the search data. With the b, w. l and t options you 
will always find at least one occurrence, which will be In the buffer 
within MonST that is used for storing the sequence. With the T 
option you may also find a copy In the system keyboard buffer. 
With these options, the Esc key Is tested every 64k bytes and can 
be used to stop the search. With the i option, which is very much 
slower, the Esc key is tested every 2 bytes. 

The search area of memory goes from 0 to the end of RAM. then 
from $FAOOOO to $FEFFFF (the cartridge and system ROM area), 
then back to 0. 

The search will start just past the start address of the current 
window (except register windows) and If an occurrence is found re¬ 
display the window at the given address. 

Searching Source-Code Windows _ 

If the G command is used on a source-code window the T sub¬ 
command is automatically chosen and If the text Is found the 
window will re-display the line containing It. 

Miscellaneous _ 


Preferences 


i This permits control over various options within MonST. The first 
three require y/n answers, pressing esc aborts or Return leaves 
them alone. 

Screen Switching __ 

Defaulting to On, this causes the display to switch to your 
program's only after 20 milliseconds. It should be switched off 
when a program is about to change a screen's address or 
resolution, then turned back on afterwards. 
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Follow Traps 


By default single-stepping and the various forms of the Run 
command treat Traps. Line-A and Line-F calls as single 
instructions. However by turning this option On the relevant 
routines will be entered allowing ROM code to be investigated. 


Important: this option should be used with care. 
Certain time critical routines, such as the floppy- or hard-disk 
drivers have portions of code designed to be atomic, i.e. not 
Interruptable, and being traced will cause malfunctions within 
such code and possible loss of data. On the other hand it can be fun 
to watch the AES as It draws pull-down menus or opens windows. 


If you have let ROM execute for a while you can interrupt it by 
pressing Shift-Alt-Help, then resume at normal speed by 
pressing ctrl-R. However the AES and VD1 both use Line-A and 
Llne-F calls and it is very likely that there are pending stack 
frames left with the Trace bit set. so having resumed a traced 
program it is likely that seemingly spurious trace exceptions will 
be generated. Pressing ctrl-R will resume at normal speed, though 
a few more such exceptions are likely until program flow reaches 
the lowest level i.e. your program. 




There Is a side effect of this that can cause machine to crash 
though: if you have traced through any AES event-type calls then 
stack frames can be created in desk accessories with the Trace bit 
set. If your program terminates before the accessory has a chance 
to respond to its own event call, a trace exception will occur q/ler 
MonST terminates and returns to the Desktop or GenST, causing 
a system crash, unless an auto-resldent MonST is Installed or the J 
notrace .prg program is used. 


NOTRACE Program 


This Is a very small program intended to be added to the auto 
folder of your boot disk which causes trace exceptions to be 
ignored, instead of producing a, largo number of bombs as it will do 
by default. The source code is a^sgs^plied. 
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Relative Offsets _- 

This option defaults to On and affects the disassembly of the 
address register Indirect with offset addressing modes, l.e. 
xxx (An). With the opUon on the current value of the given address 
register is added to the ofTset then searched for In the symbol 
table. If found It Is disassembled as symbol (An). This option Is very 
useful for certain styles of assembly language programming as 
well as high level languages which use a base register as a major 
offset, such as fflSoft BASIC which uses A3 as a pointer to the run¬ 
time system. 

Symbols Option __ 

This allows control over the use of symbols In expressions in 
MonST. It will firstly “Whether the case of symbols should be 
Ignored, pressing Y '•W# cause case Independent searching to be 
used. It will then jK#igt for the maximum length of symbols, 
which Is normally 22 but may be reduced to as low as 8. 

I__ Intelligent Copy 

This copies a block of memory to another area. The addresses 
should be entered In the form 

<start>,<inclusive_end>, <destination> 

The copy is intelligent in that the block of memory may be copied to 
a location which overlaps Its previous location. 


No checks at all are made on the validity of the move; 
copying to non-existent areas of memory is likely to crash MonST 
and corrupting system areas may well crash the machine. 


L 


List Labels 


This opens up a large window and displays all loaded symbols. Any 
key displays the next page, pressing Esc aborts. The symbols will 
be displayed In the order they were found on the disk (or In 
memory If using the Debug option from the editor). 
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Fill Memory With 


This fills a section of memory with a particular byte. The range 
should be entered In the form 

<start>,<inclusive_end>,<fillbyte> 

The warning described previously about no checks applies equally 
to this 


P_ Disassemble to Printer/Disk 

This cdsmitmd hUIgws the disassembly of an area of memory to 
printer fiff'dlalc, coffiplete with original labels and, optionally, an 
automatic list of labels created by MonST, based on cross- 
references. The first line should be entered as 

<start_address>,<end_address> 

The next line prompts for the area of memory used to build the 
cross-reference list, which should be left blank If no automatic 
labels are required else should be of the form 

<buffer_start>,<buffer_end> 

Next Is the prompt for data areas which will be disassembled as DC 
Instructions, of the form 

<data_start>,<data_end>(,<slze>1 

The optional size field should be b, w or l, defaulting to L, 
determining the size of the data. When all data areas have been 
defined, a blank line should be entered. 

Finally a filename prompt will appear; If this is blank all output will 
be to the printer, else it will be assumed to be a disk file. 

Ifssstwnatlc labels were specified there may be a delay at this point 
■ssfeife the table is generated. Automatic labels are of the form 
ixxxxx where xxxxx Is the actual hex address. 
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This Is of the form of an 8 digit hex number, then up to 10 words of 
hex data. 12 characters of any symbol, then the disassembly itself. 
Printer output may tysssSried by pressing esc. 


This Is In a form directly by GenST. consisting of any 

symbol, a tab. then the dlsaasaswSty Itself, with a tab separating 

l_, any operand from the op-co£&. Sf.gbu are disassembling an area of 

memory without loaded symbols then the XREF option should be 
used else no symbols will appear at all In the output file. Pressing 
Esc or a disk error will abort the disassembly. 

M_ Modify Address 


Included for compatibility with MonST 1, equivalent to Alt- a. 

O Show Other Bases 


Included for compatibility with MonST 1. equivalent to Alt-0. 

D_Change Drive & Directory 


This allows the current drive and sub-dlrectoiy to be changed. 

Auto-Resident MonST _ 

The additional version of MonST called AM0NST2 .PRG will now be 
described. When placed in the auto folder on a boot disk, it will be 
loaded and initialised automatically on boot-up. 

Once booted, this version of MonST lies dormant, ready to be 
invoked when any exception occurs in the machine, such as an 
add'Rss error, ft fcs intended primarily for programmers writing 
and debugging desk accessories or other AUTO-type applications, 
as if there is a problem In the code which gets called as the machine 
boots, it hang* before you get a chance to use the normal MonST. If 
required you can deliberately put an Illegal opcode, such as 
ILLEGAL. at the start of your auto program so that MonST will be 
im-oked and Ihen use It to investigate any problems your code has. 







The auto-resident version may be double-clicked from the Desktop 
and will Initialise Itself in the same way as from the AUTO folder, 
unless a version of MonST is already resident. 

Once Invoked the auto-resident version is very similar in use to the 
other versions except that programs or labels cannot be loaded 
and the base page variables are unknown and so set to 0. The other 
difference Is that when the program being debugged exits or ctrl- 
C is pressed within MonST. MonST itself stays active In memory. 

In addition any program may be interrupted by pressing the 
Shift-Alt-Help key combination when a resident version of 
MonST Is Installed. 

The resident version of MonST cannot be reclaimed from memory 
except by resetting the machine and booting with a disk which 
does not contain MonST In the auto folder. 

When an auto-resident version of MonST is loaded, the usual 
versions can still be used as normal, memory permitting, and the 
resident version will be Ignored until the non-resident version 
exits, when it will become active once again. 


Do not invoke an auto-resident MonST from within a 
program other than the Desktop, such as using Run Other from 
within GenST, as large areas of system memory will become locked 
away and unusable until a machine reset 

If both shift keys arc held down during the installation of the 
auto-resident MonST. the debugger Is itself entered, allowing the 
editing of memory or setting of BDOS breakpoints. When entered 
via this method the debugger should be left using ctrl-c when the 
debugger will remain resident. 
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Command Summary 


Window Commands 

Alt-A.Set Address 

Alt-B.Set Breakpoint 

Ait-E.Edit Window 

Ait-F.Font Size 

Alt-L.Lock Window 

Alt-0.Show Other 

Alt-P.Printer Dump 

Alt-R.Register Set 

Alt-S.Split Windows 

Alt-T.Change Type 

Alt-Z.Zoom Window 

Screen Switching 

v.View Other Screen 

Ctrl-0.Other Screen Mode 

Breakpoints 

Alt-B.Set Breakpoint 

Help.Show Help and Breakpoints 

Ctrl-B.Set Breakpoint 

U.Go Until 

Ctrl-K.Kill Breakpoints 

Ctrl-A.Set Breakpoint then Execute 

ctrl-D.BDOS Breakpoint 

Loading and Saving 

Ctrl-L.Load Executable Program 

B.Load Binary File 

s.Save Binary File 

A.Load ASCII File 

Executing Programs 

Ctrl-R.Return to program / Run 

Ctrl-z.Single-Step 

Ctrl-y.Single-Step 

Ctrl-T.Interpret an Instruction (Trace) 

r .Run (various) 

Searching Memory 

G.Search Memory (Get a sequence) 

N.Find Next 

Miscellaneous 

Ctrl-C.Terminate 

Ctrl-P.Preferences 

i.Intelligent Copy 

w.Fill Memory With 

L.List Labels 
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P.Disassemble to Printer/Disk 

m .Modify Address 

o.Show Other Bases 

D.Change Drive & Directory 

Shift-Alt-Help .Interrupt Program 
h .Show Hlstoiy Buffer 

Debugging Stratagem 

Hints & Tips _ 


If you have Interrupted a program using Shift-Alt-Help or by a 
Run Until command and have found yourself In the middle of the 
ROM. there Is a way of returning to the exact point In your 
program which called the ROM. Firstly ensure the Follow Traps 
option is on. then do Run Until with an expression of sp-a7. This will 
re-enter MonST the moment user mode Is restored which will be In 
your program. 

If you arc in a subroutine which doesn't Interest you and want to 
let It run .but return to MonST the easiest way is to use Until (not 
Run Un'ft !V,e | the expression (sp) - this sets a breakpoint 

at the ' swfe| %>*.-'<■’ If the subroutine has placed something on 
the ste&fcj (a local stack frame (normally the case for 

compile#then try Run Until (pc) ,w»4«7S which will run 
slowly wp^.iffl^-to^ctlon rts Is reached. wn't work If the 
subrouf&rfe'Sr, ■jjvrstwn calls another, so it may require a further 
condition, si&h aa'Vfpcl .w-4ei$) s (sp>xxx) where xxx Is one less 
than the current value. 

When using Run Until and you know It will take a quite a while for 
the condition to be satisfied, give MonST a hand by pre-computing 
as much of the expression as you can. for example 

<a3>(3A400-\100+Ml)) 
could be reduced to 
a3>xxx 

where xxx has been calculated by you using the Alt-0 command. 
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MonST Command Line 


If you use a CLI-type program you can pass a command line to 
MonST. consitlng of the program you wish to load and. optionally, 
a command line to pass on to It. 

Bug Hunting _ 

There are probably as many strategies for finding bugs as there 
are programmers; there Is really no substitute lor learning the 
hard way. by experience. However, here are some hints which we 
have leamt, the hard wayl 

Firstly, a veiy good way of finding bugs Is to look at the source code 
and think. The disadvantage of reaching first for the debugger, 
then second for the source code. Is that It gets you Into bad habits. 
You may switch to a machine or programming environment that 
does not offer low-level debugging, or at least not one as powerful 
you are used to. 

If a program falls In a very detectable way. such as causing an 
exception, debugging Is normally easier than If. say. a program 
sometimes doesn't quite work exactly as It should. 

Many bugs arc caused by a particular memory location being 
stepped on. Where the offending memory location Is detectable, by 
producing a bus error, for example, a conditional breakpoint placed 
at one or more main subroutines can help greatly. For example, 
suppose the global variable main_ptr fs somehow becoming odd 
during execution, the conditional expression could be set up as 

fmain_ptr)SI 

If this method falls, and the global variable Is being corrupted 
somewhere un-detectable. the remaining solution Is to Run Until 
that expressless, which could take a considerable time. Even then It 
may not find ft, for example If the bug Is caused by an Interrupt 
happening at a certain time when the stack Is In a particular place. 


HiSoft DevpocST 


Debugger 


Page 115 


Count breakpoints are a good way of tracking down bugs before 
they occur. For example, suppose a particular subroutine is known 
to eventually fail but you cannot see why. then you should set a 
count breakpoint on it. then let the program run. At the point 
where the program stops, because of an exception say. look at the 
value of the count breakpoint (using Help). Terminate the program, 
re-load it. then set a stop breakpoint on the subroutine for that 
particular value or one before it. Let it run. then you can follow 
through the sub-routine on the very call that is falls on, to try and 
work out why. 

Good luck! 

AUTO-folder programs _ 

If these crash during Initialisation then use amonst (which must be 
before your program in the directory) to catch the exception. 
Including a deliberate illegal Instruction at its beginning will let 
you single-step the Initialisation. 

Desk Accessories_ 


If an accessoiy Is mls-behaving during normal execution then use 
AMONST. To find a desk accessory in memory, enter the debugger by 
pressing Shift-Alt-Help then start looking from location 0 for 
the upper-cased name of your .ACC file, padded to eight characters 
with spaces. Ignore occurrences within directory buffers (these will 
be followed by .ACC) and In MonSTs own buffer (these will be 
preceded by an ASCII T character). The correct occurrence will have 
a longword 12 bytes after the start of the name. This will point to 
the basepage of your accessory and $100 bytes after that will be 
the start of your program. From looking at this you should be able 
to find your main loop and set a suitable breakpoint. Normal 
execution should be resumed with ctrl-R then MonST will be re¬ 
entered when your breakpoint is reached. 

If an accessory is misbehaving during its initialisation then you 
have to stop it at the very beginning before it has a chance to do 
anything. The recommended way is to re-assemble the accessory 
with an illegal instruction at the beginning and let amonst catch 
It. but this is sometimes not possible. There follows a method that 
works on current ST ROMs to stop the AES just before it executes 
your program, but please note the method is complicated and not 
recommended for beginners 
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Firstly hold down both shift keys to enter amonst during the boot 
sequence then set a BDOS Breakpoint on the Open call, $3D. then 
press ctrl-c to let the boot sequence resume. 

MonST will be re-entered every time something tries to Open a file, 
so make window 3 the current window and after every BDOS 
breakpoint is hit set its address to (sp+2) - if the name is not your 
accessory then Ctrl-Z, to execute the Open call, set another BDOS 
breakpoint on $3D then Ctrl-R, and try again. If the name ts your 
accessory then set a BDOS breakpoint on $4B, then Ctrl-R. 

L MonST will then be entered Just before It loads the accessory, so 
W ' ctrl-z to do the GEMDOS call, then Ait-B and enter d0+100 
which sets a breakpoint on the very first Instruction. Now Ctrl-R 
and the next time MonST appears it will be op the first instruction 
of the accessory. This method takes a while but it’s often the only 
way of finding bugs in accessories. 

Exception Analysis __ 

When an unexpected exception occurs, it’s very useful to be able to 
work out where and why it occurred and. possibly, to resume 
execution. 

Bus Error _ 

If the PC is in some non-existent area of memory then look at the 
relevant stack to try and find a return address to give a clue as to 
the cause, probably an unbalanced stack. If the PC is in a correct 
area of your program then the bus error must have been caused by 
a memory access to non-existent or protected memory. Recovering 
from bus errors and resuming execution is generally not possible. 

Address Error _ 

If the PC is somewhere strange the method above should be used, 
otherwise the error must have been caused by a program access to 
an odd address. Correcting a register value may be enough to 
resume execution, at least temporarily. 
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Illegal Instruction 


If the PC Is in very low memory, below around $30. it is probable 
that It was caused by a jump to location 0. If you use MonSTT to look 
here you will see a short branch together with, normally, various 
ORI instructions (really longword pointers) and eventually an 
Illegal Instruction. 

Privilege Violation _ 

This is caused by executing a privileged Instruction In user mode. 
normally meaning your program has gone horribly wrong. 
Bumping the PC past the offending Instruction is unlikely to be 
much help In resuming the program. 
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CHAPTER 5 
Linker 


Introduction 


, A linker's Job Is to accept one or more input files generated with 
GenST or a high-level language compiler and create a single 
executable file from It. One of the most powerful features is library 
searching, which means that the linker will only use the parts of a 
library of modules that are required by other sections of the 
program, resulting In much smaller output files. 

There are unfortunately two different linker file formats on the 
Atari ST. known as DRI- and GST-formats. While GenST can 
generate both formats, only the GST-format Is supported In the 
LlnkST linker. To link DRI code you need either the Atari aln 
program or the Digital Research LINK68 and relmod programs. 


LlnkST will only link GST format flies. 


Invoking the Linker _ 

i The simplest way to run the linker from the Desktr ' 0 ‘$i 
^ click on the linkst . ttp icon, and enter a i : 

There Is another way to Invoke the linker, uft vs f 
contains the required options. 

The comcxan :; line contains the necessary Information for the 
linker to resugS all. the relevant flies, and generate an output file. 


HiSoft De&pacsr 


Linker 


Page 119 


Command Line 


The command line should be of the form: 

<£ilonamo> <-optiona> [filename] [-options] 

Options are denoted by a - sign then an alphabetic charcf/tp',. 
allowed options being: 

b generate a true BSS section for any such named sections 

d debug - Include all symbols In the binary file using DR 
standard 8 character format (for MonST or other debuggers) 

f force pass 2 of the linker, useful If you want to see all errors 
(as any pass 1 errors will by default stop the link before the 
second pass) 

l specify that all following filenames are library filenames 

m dump a map file showing the order of the sections and labels, 
will be the main filename with an extension of .map 

0 specify object code filename, may be followed by white space 
before filename 

Q 'quiet' mode, which disables the pause after the link 

s dump a symbol table listing, will be the main filename with 
an extension of . sym 

x extended debug, using the HtSoJt Extended Debug format 
w specify control file filename, defaults to . lnk extension 

Normally any filenames given are taken to be Input files, defaulting 
to the extension of . bin. though If a . lnk extsftsSen Is specified It 
will be taken to be a control file, or after a -L epOora filenames are all 
assumed to be libraries. 

The output filename can be specified with the -o option on the 
command line, or using the output directive In the control file. If 
there Is more than one of these, the last one is used. If there Is 
none, then the first Input filename specified in the command line 
or control file Is used with an extension of . prg. 
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Example Commond Lines 


PARTI PART2 -d 

Reads parti.bin and part2.bin as input flies, and generates 
parti . prg as an output file complete with debugging information. 

PARTI PART2 -O TEST.PRG 

Reads parti.bin and part2.bin as input files, and generates 
test . prg as an output flic. 

-O TEST.TOS START -1 MYLIB -s 

Reads start.bin as an input file, selectively reads mylib.bin as a 
library, and generates the output flic test . tos and the symbol 
listing file TEST. SYM. 

LinkST Running _ 

LlnkST has two passes - during pass 1 it builds up a symbol table 
of all sections and modules, and during pass 2 it actually creates 
the output file. When It starts It prints a logon message, then 
reports on which flies it is reading or scanning during both passes. 
This gives you some idea of what takes time to do. as well as exactly 
where errors have occurred. 

If there is enough free memory at the end of pass 1 LinkST will use 
a cache to store the output Ale. which greatly speeds up the 
process. If it uses the cache it will write to the disk at the end of 
pass 2, and report the number of errors. 

' W When the link finishes you will be prompted to press a key before 
quitting. This is to give you an opportunity to read any warning or 
error messages before returning to the Desktop. You can disable 
this pause by using the -q option, useful if you are using a CLI or 
batch file program. 

LinkST was especially optimised for speed, though the speed of the 
ST floppies is still a restricting factor. If you can't afford a hard 
disk we recommend the use of a RAM disk which can make great 
improvements, but leave enough memory free for the linker to 
cache your output file. If you are limited in what you can fit on your 
RAM disk we recommend you put many small library or input flies 
on there. 
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Error and warning messages are directed to the screen - if you 
want to pause output you can press ctrl-S, and ctrl-Q will 
resume it. Pressing ctrl-c will abort the linker immediately. You 
can re-direct screen output to a disk file by starting the command 
line with 


>FILENAME.TXT 

or you can re-direct it to a printer by starting the command line 
with 

>prn: (parallel port) or >aox: (serial port) ^ 

If you do re-direct output in this way you should use the -q option 
as you won't be able to see the prompt at the end of the linking. 

Control Files 


The alternate way to run the linker is to have a control file for the 
programs which you are linking together. 

If you require a lot of options which won't fit on the command line 
or you get bored of typing them you can use a control file, which is 
a text file containing commands and filenames for the linker. The 
default extension is . lnk, and the text file can be generated with 
GenST (though don't try and assemble it I). The control filename is 
specified on the command line with the -w (for With) option, and 
each line can be one of the following: 

INPUT <fllename> 

This specifies a filename to be read as an input file. The default J 
extension is .bin If none Is given. 

OUTPUT <filename> 

This specifies the filename to be used for the output file. There is no 
default extension - you should specify it explicitly. 

LIBRARY <filename> 

This specifies a filename to be scanned as a library. The default 
extension Is . BIN if none is given. 
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SECTION <sectlonname> 

This allows specific section ordering to be forced. 

DS8UG 

Ail symbol names Included In the link are put In the output 63« so 
that debugging programs such as MonST can use them when She 
program Is running. 

XDEBUG 

Similar to debug option but uses HiSoJt Extended Debug format for 
up to 22 character significance. 

DATA slze(K) 

The BSS segment size Is set accordingly. The size can be given 
either as a number of bytes or as a number of K-bytes (units of 
1024). This option is particularly useful for compilers like 
Prospero Pascal which store their variables In the BSS segment. 
Blank lines in the control file are Ignored, and comments can be 
Included by making the first character In the line a *. a ; or a I. 

BSS <sectlonname> 

Specifies that the named section should lie In the GEMDOS BSS 
section area. This can save valuable disk space, but will generate 
errors if the section contains any non-zero data. This should not 
be used at the same time as the DATA statement. 


^ With the INPUT or OUTPUT dliJSvfc'PiS the filename Is specified as * it 
is substituted for the first fikrsetue on the command line. This can 
be useful for having a generic cwdrol file for linking C programs, 
for example. 
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An example control file Is: 

* control file for linking C program 
INPUT STARTUP 
INPUT * 

XDEBUG 
LIBRARY CLIB 

Assuming this control flic Is called cprog.lnk, the LlnkST 
command line 

TEST -w CPROG W 1 

will read as Input files STARTUP.BIN and TEST. bin, and scan the 
library clib.bin. The object code. Including extended debug 
information, will be written to test.PRG. as none was explicitly 
specified. 

If you do not specify a drive name In the control file or on the 
command line, the default drive will be assumed. If you run LlnkST 
from the Desktop, the default drive will always be the same as the 
file on which you double-clicked: though If you run it from a CLI or 
from the GenST editor this will not necessarily be so. 

Automatic Double-Clicking _ 

It Is possible to install LlnkST so that you can double-click on a 
. lnk file from the Desktop to Invoke the linker, by using the Install 
Application option from the Desktop. This is a similar process to 
that described for GenST. except the type should be left as TOS 
Take Parameters and the extension should be . lnk 

LinkST Warnings _ ^ 

Warnings are messages indicating that something might be 
wrong, but It's nothing too serious. 

duplicate definition of value for symbol "x" 

The symbol was defined twice. This can happen if you replace a 
subroutine in a module with one of your own. for example. The 
linker will use the first definition It comes across, and give this 
warning on thesfiSBBd. 
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module name is coo long 

Module names can only be 80 characters long. 

comment is too long 

Comment directives are only allowed to be 80 characters long 
(don't ask us why. we don't knowl). 

absolute sections overlap 
'w Two absolute sections clash with each other. 

SECTION ”x" is neither COMMON nor SECTION 
A section name was specified without defining Its type. 

LinkST Errors _ 

LlnkST errors divide Into four areas: general errors, I/O errors, 
binary file errors, and linker bugs. In some error messages a string 
Is Included, denoted by "x" below. In others a number may be 
output, denoted by 99 below. 

Generol Errors _ 

unresolved symbol "x” in file "x" 

The symbol was referred to but not defined In the file. There may 
also be other files which refer to the symbol, but this gives you a 
start In your searchl 

'w 

XREF value truncated 

A value was too large to fit Into the space allocated for It. for 
example a bsr to an external may be out of range. 

bad control line "x" 

An Illegal line was found In a control, iffies 
non-zero data in BSS section 

A section wanted as a true BSS section contained non-zero data. 
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Input/Cvfrsfi ,70) Error s . . 

file "x* not found 
Can't open output filtg. ’y“ 

Can't open map file "x" 

Can't open symbol file "x" 

Can't open input file "x” 
i/o error on input file 
disk write failed 
filename "x" was too long 

Binary File Errors __ ^ 


These are errors in the Internal syntax of the input file, and should 
not occur. If they do it probably means the compiler or assembler 
produced incorrect code. 


missing SOURCE directive 

Can occur if a file is not in GST format, for example a DRI file. 


I 


runtime relocation is only available for LONGs 
attempt to redefine id of symbol "x" 
attempt to DEFINE "x" with <id> of zero 
bad operator code 0x99 in XREF directive 
bad truncation rule in XREF 
wrongly placed SOURCE directive 
bad directive 99 

<id> 99 not DEFINEd as a SECTION but used as one 

attempted re-use of <id> 99 as SECTION id 

attempted re-use of ”x" as SECTION name 

section is COMMON but being used as though it's not 

SECTION is being misused as COMMON 

unexpected end of input file 

Linker Bug' Messages _ 




These can be produced as a result of internal checks by the linker. 
If you get one please send us copies of the flies you are trying to 
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Appendix A 
GEMDgS #fror codes 

This appendix detsife the numeric GEMDOS errors and their 
meanings. The error numbers Shown are those displayed by 
MonST and GenST: when calling GEMDOS from your own 
programs these values will be negative. 


0 OK (no error) 32 

1 Fundamental error 33 

2 Drive not ready 34 

3 Unknown command 35 

4 CRC error 36 

5 Bad request 37 

6 Seek error 39 

7 Unknown medium 40 

8 Sector not found 

9 No paper 46 

10 Skit,® .fault 49 

11 i$*M”;&ult 50 

12 General error 64 

13 Write protect 65 

14 Medium change 66 

15 Unknown device 

16 Bad sectors on format 67 

17 Insert other disk 


Invalid function number 

File not found 

Path not found 

Too many files open 

Access denied 

Invalid handle 

Insufficient memory 

Invalid memory block 

address 

Invalid drive 

No more files 

Disk full (not a GEMDOS 

error; produced by GenST) 

Internal error 
Invalid program load 

Setblock failure due to 
growth restrictions 
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Appendix B 
GenST error messages 


GenST can produce a large number of error messages, most of 
which are pretty well self explanatory. This appendix lists them all 
In alphabetic order, with clarifications for those which require 
them. 

Please note that GesaSt‘» continually being Improved and this list 
may not agree exat:^T«&h the version you have, there may be 
additional messages xx-'A documented here. 

Errors __ 

If you get a message beginning with internal please tell us - you 
should never see i&ese. 

.w or .L expected as index size 
absolute expression MUST evaluate 
absolute not allowed 
additional symbol on pass 2 

somehow a symbol has appeared during pass 2 that did not 
appear during pass 1 

address register expected 

addressing mode not allowed 

addressing mode not recognised 

BSS or OFFSET section cannot contain data 

OFFSET sections and non-GST BSS sections can only contain 
DS directives 

cannot create binary file 

could be a bad filename, or a write-protected disk. etc. 
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cannot nest MACRO definitions or define in REPTs 

macro definitions may not be nested or defined within 
repeat loops 

cannot nest repeat loops 
comma expected 
data register expected 
data too large 
division by zero 
duplicate MODULE name 
module names must be unique 
error during listing output 

listing will be stopped at this point 
error during writing binary file 
normally disk full, 
executable code only 

only executable code may be assembled to memory 

expression mismatch 

normally a syntax error within an expression 

fatally bad conditional 

there were more ENDCs in a macro than IFs 
file not found 
forward reference 
garbage following instruction 
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illegal BSR.S 


a BSR.S to the following Instruction Is not allowed - change it 
to BSR 

illegal type combination 
immediate data expected 
imported label not allowed 
include file read error 
instruction not recognised 
invalid FORMAT parameter 
invalid IF expression, ignored 
invalid MOVEP addressing mode 
invalid number 
invalid numeric expansion 

the symbol Is not defined or relative or a syntax error 
invalid option 
invalid printer parameter 
invalid register list 
invalid section name, TEXT assumed 
invalid size 
line malformed 
linker format restriction 

the DRI format Is restrictive about where It allows Imports 


local not allowed 
missing close bracket 
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missing ENDC 

there were more IFs then ENDC® 
missing quote 
misuse of label 
not yet implemented 
number too large 
odd address 

option must be at start 
ORG not allowed 
out of memory 
phasing error 

should never happen, look Investigate Immediately before 
first such error 

program buffer full 

change the program buffer size when assembling to memory 
register expected 
relative not allowed 
relocation not allowed 
repeated include file 

each include file may only be included once on each pass 
8®wrce expired prematurely 

within an IF. MACRO or REPT and the source ran out 
spurious ENDC 
spurious ENDM ©3? ISEXIT 
spurious ENDE 


Pepj *32 
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symbol defined Cwice 
symbol expected 
undefined symbol 
user error 

caused by a FAIL directive 
wrong processor 

XREFs not allowed within brackets 



68010 instruction, converted to MOVE SR 


MOVE OCR, Is not a 68000 Instruction 
branch made short 
by optimising 
directive ignored 
invalid LINK displacement 
If negative or odd 
offset removed 

xx(An) form reduce to (An) by optimising 
y»3,*tive cannot be relocated 
ih&ift branch converted to NOP 
sign extended operand 

data In MOVEQ needed sign extension to fit 


vJ 
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Appendix C 
ST Memory Map 


This Appendix details certain Information about the ST memory 
map: 

1. Processor Dump area 

2. Base Page layout 

3. Hardware memory map 

Processor Dump Area _ 

When the ST crashes with an exception (l.e. mushrooms or bombs) 
It stores a copy of the processor's state In an area of memory 
which Is not destroyed by a RESET. Thus after such a crash you 
can load MonST and Investigate the relevant area of memory to try 
to ascertain what exactly went wrong. If this happens a lot you 
should the auto-resldent version of MonST so you will have a much 
better Idea of the cause of the problem. 

$380 long contains $12345678 If valid 

$384 8 longs saved values of D0-D7 

$3A4 8 longs saved values of A0-A7 (SSP) 

$3C4 byte exception number 

$3C8 long saved USP 

$3CC 16 words copied from the SSP 
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Base Page Layout 


Every program that runs under GEMDOS has a base page area 
which contains certain Information. It Is $100 bytes long. 


Offset 

Name 

Contents 

$00 

pjowtpa 

base address of the TPA (I.e. here) 

$04 

p.hltpa 

pointer to end of TPA +1 

$08 

p_tbase 

pointer to start of TEXT area 

$0C 

pjlen 

length of TEXT area 

$10 

p_dbase 

pointer to start of DATA area 

$14 

p_dlen 

length of DATA area 

$18 

p_bbase 

pointer to start of BSS area 

$1C 

p_blen 

length of BSS area 

$20 

p_dta 

pointer to DTA address 

$24 

p_parent 

pointer to parent's base page (0 if desk acc.) 

$28 


(reserved) 

$2C 

p_env 

pointer to environment string 

$80 

p_cmdlln 

command line: length byte then string, which 
Is not guaranteed to be null-terminated 

$100 


your program starts here 
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Hardware Memory Map 
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Appendix D 
Calling the Operating 
_System_ 


The operating system of the ST is large and complex and consists 
of various levels. To help In your own program development, this 
appendix describes the calling mechanisms and routines available, 
but it is not Intended to be definitive. It also details the various 
example programs and Include files supplied with DevpacST. The 
various levels of the operating system are: 


GEM AES window and event manager 

GEM VDI device-independent graphics routines 

GEMDOS disk and screen I/O. similar to MS-DOS 

BIOS low level I/O 

XBIOS extended low level I/O 


Each of these will now be described In varying degrees of detail. 


GEMDOS - Disk and Screen I/O 


GEMDOS was converted from CP/M 68k and Is similar In many 
ways to generic CP/M but with extra facilities (e.g. sub-directories) 
taken from MS-DOS. It Is responsible for disk I/O and character 
I/O via the screen, keyboard, serial and parallel ports. It Is also 
responsible for memory management. 

GEMDOS was designed to be called directly from C. so all 
parameters are put onto the stack and have to be removed 
afterwards. The calling sequence from assembler Is of this general 
form: 


move ??,-<a7) 

move.w #??,- (a7) 
trap #1 

add.l #??,a7 


put parameters on stack 
the function number 
call GEMDOS 
restore the stack 
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After the call the stack has to be corrected; while an ADD.L can be 
used as above. It is slow and takes six bytes. If the stack needs 
correction by 8 bytes or less, the best way is to use 

add.1 #??,a7 

which takes two bytes. If it has to be corrected by more than 8 
bytes, the best way Is 

lea ??(a7),a7 

which takes four bytes. Both methods are smaller and faster than 
the flrst method. Incidentally, a major source of bugs when 
starting programming with GEMDOS is forgetting to correct the 
stack, or correcting it by the wrong value. 

Program Startup and Termination _ 

When a GEMDOS program starts up It owns all free memory - that 
Is the memory from the end of the program through to the end of 
usable RAM (normally Just before the screen) Is owned by the 
program, which Is Just as well as the stack Is at the very end of this 
area. 

If any memory management calls (such as m_olloc) are required, 
you wish to execute other programs within yours, or If you are 
writing a GEM program. It Is important to give back some of this 
memory. If you don't there will be no free memory for these uses. 
This Is normally done during at the beginning of programs using 
the m.shrink call, utilising the fact that a pointer to the programs 
basepage is 4 bytes down on the stack, like this: 

move.1 
add.l 
add.l 
add.l 
add.l 
move.1 

move.1 
clr.w 

lea P 


4<a7),a3 
$C(a3), dO 
$14(a 3),dO 
Sic(a3),dO 
•extra,dO 
#$100,dO 
tmystaclc, a 7 
dO,-(a7) 
a3,-(a7) 
-<a7) 

#$4a,-(a7) 

#1 

12(sp),sp 


basepage 

data length 
BSS length 

any additional memory 
basepage length 
before shrinking 


do the shrink 
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The extra bytes may be required for your programs storage. Note 
that you should move the stack to a safe area before the shrink, 
otherwise the stack will be in memory that Is not owned by your 
program and liable to corruption. 

A GEMDOS program can terminate In one of three ways: p_termO. 
which Is not recommended. p_term. the normal way to finish a 
program, and p_termres, for system patches and the like. For 
normal termination use this code: 

clr.w -(a7) no return code 

move.w #$4c,-(a7) p_terra 

trap #1 

When a program terminates all memory It owns Is freed and any 
open files are closed. 

GEMDOS Summary _ 

The calls will now be described In numeric order by giving the size of 
the parameters. In the order they should be placed on the stack, 
and the stack correction number. For example, using function call 
2. c_conout, to print the character x, the code would be 

move.w #’X',-(a7) the character 

move.w 12,-(a7) the function number 

trap #1 call it 

addq.l #4,sp then correct 

At present GEMDOS calls corrupt registers dO and aO only, but 
this is not documented. We therefore recommended programmers 
to assume that registers d0-d2/a0-a2 are corrupted. In a similar 
way to the other operating system calls. 

0 - Terminate Process (old form), pJermO 
Parameters: None 

Result: None 

Stack: 2 

This terminates the current program, with a return code of 0. It Is 
recommended that p_term (function $4c) should be used In 
preference to this call. As control never returns after the call, no 
stack correction is actually required. 
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1 - Read character from keyboard, c_conln 

Parameters: None 

Result: D0.L=key code 

Stack: 2 

This waits for a key to be struck, echoes It to the screen, and 

returns Its value. The long result has the ASCII value In the lowest 
8 bits, and a physical key number is returned In bits 16-23. All 
other bits are set to 0. 

2 - Write character to screen, c_conout 

Parameters: word: character 
Result: None 

Stack: 4 

This writes the given character to the screen. A 16-blt parameter is 
supported for future expansion, so bytes should always be ANDed 
with $FF before the call, though currently the upper 8 bits are 
ignored. 

3 - Read character from serial port, c_auxln 

Parameters: None 

Result: DO.B=character read 

Stack: 2 

This waits for a byte to be received from the auxiliary device, which 
is the serial port. 

4 - Write character to serial port, c_auxout 

Parameters: wordxharacter 

Result: None 

Stack: 4 

This sends the character out via the serial port. As with function 2, 
the upper 8 bits of the word should be 0 for upward compatibility. 

5 - Write character to printer, c_prnout 

Parameters: word: character 

Result: DO.W=0 If failed. -1 if OK 

Stack: 4 

This sends the character out via the parallel printer port. As with 
functions 2 and 4 above, bits 8-15 of the word should be 0. 

6 - Raw I/O to standard I/O, c_rawio 

Parameters: word: character for output, or $00FF to read 
Result: DO.W If $00FF passed 

Stack: 4 

If the character is passed as $00FF then the keyboard is scanned 
and a result returned in DO.W (or 0 if no key available). If the 
character is not $00FF, then it is printed on the screen. 
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7 - Raw Input from keyboard, c_rawcin 

Parameters: None 

Result: DO.L=character read 

Stack: 2 

This waits for a key to be pressed and returns Its value. It does not 
echo it to the screen. 

8 - Read character from keyboard, no echo, c_necin 

Parameters: None 

Result: DO.L=charactcr read 

Stack: 2 

'w This waits for a key to be pressed and returns its value. It does not 
echo, but the control keys Ctrl-C, Ctrl-s and Ctrl-Q are 
Interpreted In their usual way - ctrl-c will abort the program, 
Ctrl-s will pause output and ctrl-Q will resume it. 

9 - Write string to screen, c_conws 

Parameters: long: address of string 

Result: None 

Stack: 6 

This writes the given null-terminated string to the screen. 

$A - Read edited string from keyboard, c_conrs 
Parameters: long: address of Input buffer 

Result: None 

Stack: 6 

Before calling this, the first byte of the buffer should be set to the 
size of the data portion of the buffer. On return, the second byte In 
the buffer will be set to the length of the string, and the string itself 
starts at the third byte. No CR or null Is stored in the returned 
string and pressing Ctrl-C will terminate the entire program. 

< $B - Check sfalus of keyboard, c_conis 
Parameters: None 

Result: D0.L=-1 If character available. 0 If none 

Stack: 2 

This returns the status of the keyboard. The key Itself should be 
read with another call. 

$E - Set default drive, d_setdrv 
Parameters: word: drive number 
Result: D0.L=bit map of drives In the system 

Stack: 4 

This sets the default drive: a word of 0 denotes A:, 1 denotes B:, etc. 
The returned value has a bit set for each installed drive, bit 0=A:, bit 
1=B:, etc. 
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$10 - Check skjitsac? standard output, c_conos 
Parameters: None 

Result: D0.L=-1 if ready. 0 if not 

Stack: 2 

This tests to see If the console device is ready for output. 

$11 - Check status of printer, c_pmos 
Parameters: None 

Result: D0.L=-1 if ready. 0 If not 

Stack: 2 

This tests the status of the printer port. If the printer is ready to 
receive a character it returns -1. else it returns 0. W* 

$12 - Check stw ^ .serial port input, c_auxis 
Parameters: 

Result: £©.£=-1 If character waiting, 0 if not 

Stack: 2 

This tests the serial port and returns -1 if there is a character 
waiting to be read. 

$13 - status of serial port output, c.auxos 

Parameter fi'i None 

Result: D0.L=-1 if ready, 0 if not 

Stack: 2 

This tests the serial port and returns -1 if it is ready to receive a 
character. 

$19 - Get default drive, d_getdrv 
Parameters: None 

Result: D0.W=d*ive number 

Stack: 2 

This returns the numb^'^f i&e current drive, with A:=0. B:=l etc. 

$1A - Set disk transfer oQdans, f_setdta 
Parameters: long: pointer to disk transfer address 

Result: None 

Stack: 6 

This sets the address of a 44-byte buffer used for searching for 
filenames. It must be word-aligned. 
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$20 - Get into Supervisor/User Mode, 

Parameters: long: value for stack; cw 0 fir l 

Result: D0.L=(depends on 

Stack: 6 

This has two functions - It can tell you tf the psogram Is In User or 
Supervisor mode and It can switch fea» one ssicde to another. To 
find which mode the processor la ia, fiaS. fella routine with a 
parameter of 1. The return value will be 0 for iaeei mode, and -1 for 
supervisor. To switch modes you have to supply a new stack 
pointer, or pass 0 If you want the stack to remain unchanged. For 
example. If you are In user mode and want to switch to supervisor 
mode using a SSP at address myssp. the code would be: 

move.l Hrayssp,-(a7) 
move. w #S20,-(a7) 

trap #1 

addq.l #6,a7 

When switching to supervisor mode the old value of the SSP Is 
returned In dO.I. If you only want to go temporarily Into Supervisor 
mode to hack protected memory, for example. XBIOS call supexec 
is a lot easier. 

$2A - Get date. Lgetdate 

Parameters: None 

Result: DO.W 

Stack: 2 

This reads the date, with the result In this format: 

Day: bits 0-4 

Month: bits 5-8 

Year bits 9-15 (since 1980). 

$2B - Set date, Lsetdate 

Parameters: word: date 

Result: None 

Stack: 4 

This sets the date, using the same word format as the previous 
function. 
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$2C - Get time, t_gettime 

Parameters: None 

Result: DO.W 

Stack: 2 

This returns the time of the day. with the result In this format: 
Seconds/2: bits 0-4 

Minutes: bits 5-10 

Hours: bits 11-15 

$2D - 

Paran a;;,:?:- time 

Result; ''' 

Stack::. - 

This time of day. In the same word format as the 

prevto^fB^^iQBa;" 

$2F - Get disk transfer address. f_getdta 
Parameters: None 

Result: DO.L=pointer to disk transfer address 

Stack: 2 

This re&SSSUKtJie current disk transfer address, and should always 
be evert 

$30 - Get version number, s_verslon 
Parameters: None 

Result: DO.W=verslon number 

Stack: 2 

This returns the GEMDOS version numbs:?,, 'i&th the major 
number in the low byte, and the minor nun).?.;, -:;; the high byte. 
Known releases at this time are: 

$0D00 version 0.13 (obsolete disk-based) 

$ 1300 version 0.19 (ROM-based) 

$31 - Terminate and stay resident, pjermres 
Parameters: word: exit code, long: bytes to keep 
Result: None 

Stack: 8 

This allows a program to terminate while keeping part or all of it in 
memory. It is useful for programs which extend the system, such 
as RAM disc drivers: If they terminated normally the memory they 
lie in would ggt&ns&qyed when the next program loaded. The 
memory that c s."-. 5*® retained is that starting at the base page, and 
the length para/isja?’ should include the $100 of the base page, the 
required progrstfi teagth. data and stack space if relevant. 
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$36 - Get drive free space, d_free 

Parameters: word: drive code, long: pointer to buffer 

Result: None 

Stack: 8 

This returns various bits of Information about a particular disk 
drive. The drive code should be 0 for the default drive. 1 for A:. 2 for 
B:, etc. The buffer should be 16 bytes long, and word aligned. On 
return. It will contain 4 longs of Information: free space, number of 
available clusters, sector size (In bytes), and cluster size (in 
sectors). 

' w $39 - Create a sub-directory, d.create 

Parameters: long: address of pathname 

Result: DQ.W=0 If OK. else error code 

Stack: 6 

This creates a new directory, according to the nufik-teriirds^atAd 
string. 

$3A - Delete a sub-directory, d.delete 
Parameters: long: address of pathname 

Result: D0.W=O If OK. else error code 

Stack: 6 

This deletes a directory, so long as it has no files or other 
directories In It. 

$3B - Set current directory. d_setpath 
Parameters: long: s&freas of pathname 

Result: DO.Wa© Sf '$&, else error code 

Stack: 6 

This sets the current directory, according to the null-terminated 
string. Note that drive specifiers are not allowed - you should set 
the current drive then its directory. 

' w $3C - Create a file, f_create 

Parameters: word: attributes, long: pointer to string 
Result: D0.W=fUe handle If successful, else error (and 

longword negative) 

Stack: 8 

This will attempt to create the given file and If successful will return 
a file handle that can be used In other file GEMDOS calls. The 
attribute word can be these values: 

01 read only 

02 hidden file 

04 hidden system file 

08 filename contains volume name in first Xt. 


HiSoff DevpaeST The Operating System 


fasrw 


File handle numbers returned by this call and the following one 
start are words normally starting at 6 and go upwards. Handles 0 
to 5 are standard handles which are already open when a program 
starts. They correspond to the following devices: 

0 - console input 

1 - console output 

2 - serial port 

3 - parallel port 

There are three system device names, called CON:, AUX: and PRN: 
which can be used with this and the following call. They return 
negative words, so to distinguish these from error returns always 
TST.L / BMI for the error case. 

$3D - Open a file, f_open 

Parameters: word: mode, long: pointer to filename 
Result: DO.W=flle handle if successful, else error (and 

longword negative) 

Stack; 8 

This an existing file for reading, writing, or both. The 

mode word must be one of the following: 

0 open to read 

1 open to write 

2 open for both reading and writing 

If successful this will return a handle which can be used 
subsequently, else an error number. 

- Close file, f_closo 

Parameters: word: handle 

8es?jst: D0.W=0 If OK. else an error number 

Stack 4 

GSrea a file handle this will close the file. Do not close a standard 

harsdte. 


ESSF*. 


This call, along with all the others that require 
handles, do not do very extensive checks on the validity of the 
handle. If you pass an invalid one you may get an error return, or 
the machine may crashl 
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$3F - Read file, f_read 

Parameters: long: load address, long: number of bytes to read, 

word: handle 

Result: DO.L=number of bytes read, or an error code 

Stack: 12 

This will attempt to read bytes from the given Ole. If an error occurs 
DO. l will be negative. If the end of file is reached during the read 
operation an error code Is not returned - If you wish to check for 
this you have to compare the number of bytes you asked for with 
the result - If they are different then you tried to read past the end 
of flic. 

$40- f.write 

Para‘-r.'-.ft'- long: start address, long: number of bytes to write, 
word: handle 

Result: D0.L=number of bytes written, or an error code 

Stack: 12 

This will attempt to write bytes to the given file. If an error occurs 
DO.L will be negative. If the disk becomes full an error code will not 
be Issued, but the value returned will not be the sacje the value 
passed to It as the number of bytes to write. 


If you pass a negative length parameter GEMDOS will 
crash very badly 


$41 - Delete File, f_delete 
Parameters: long: pointer to filename 

Result: D0.W=0 If successful, else error code 

Stack: 6 

This will attempt to delete the given file. 

$42 - Seek file pointer, f_seek 

Parameters: word: mode, word: file handle, long: position 
Result: D0.L=absolute position In file after seek 

Stack: 10 

This will move the file pointer to a given position in the file. The 
mode word should be one of the following: 


0 move to N bytes from the start of the file 

1 move to N bytes from the current location 

2 move to N bytes from the end of the file 


If you try and move past either end of the file you will get a result of 
0 (for the start) or the actual length of the file. 
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$43 - Get/Set file attributes, f_attr!b 

Parameters: word: attributes, word: get/set. long: pro Inter to 

filename 

Result: DO.W=new attributes, or an error code 

Stack: 10 

This can be used to get or set the attributes for a given file. The 
attribute's word can be: 

01 read only 
02 hidden file 

04 hidden system file 

08 filename is actually the volume label In first 11 bytes 

$10 sub-directory 

$20 file Is written and closed 

TTie other word should be 0 to Get the attribute, or 1 to Set it. 

$45 - Duplicate File Handle, f_dup 
Parameters: word: standard handle 

Result: D0.W=new handle, or error code 

Stack: 4 

Given a handle to a standard device (0-5), this function returns 
another handle that can be used to address the same device. It can 
also be closed without affecting the standard device handle. 

$46 - Force file handle, fjorce 

Parameters: word: non-standard handle, word: standard 
handle 

Result: D0.W=O if OK, else error code 

Stack: 6 

This forces the standard handle to point to the same device or file 
as the non-standard one, and can be used, for example, to re-direct 
screen output to a disk file. 

$47 - Get Current Directory, d_getpath 
Parameters: word: drive number, long: pointer to buffer 
Result: D0.W=0 if OK, else error code 

Stack: 8 

Given a drive number (default drive=0, A:=l, B:=2 etc.) this will 
return the current directory in the given buffer, in null-terminated 
form. The buffer should be 64 bytes long. 
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$48 - Allocate Memory, m_alloc 

Parameters: long: number of bytes required 

Result: DO.L=address of memory allocated, or 0 If failed 

Stack: 6 

This allocates the given amount of memory from the system pool. 
If available. When a program terminates all its memory allocations 
are cleaned up. This call can also be used to find the amount of free 
memory. If -1 is passed. 


When GEMDOS Itself uses this call It always ensures 
the number of bytes required is even, so we recommend this out of 
paranoia. This call can occasionally return an odd value for the 
start of the allocated memory under TOS 13. 


$49 - Free Allocated Memory, m_free 
Parameters: long: address of area to free 

Result: D0.W=O If OK, else an error code 

Stack: 6 

This frees a block of memory allocated with m_alloc above. 

$4A - Shrink Allocated Memory, m.shrlnk 
Parameters: long: length to keep, long: start address to keep, 

word: 0 

Result: D0.W=0 if OK. else an error code 

Stack: 12 

This is normally used when a program starts up and releases part 
of the allocated memory back to GEMDOS. 

$4B - Load or Execute @ Pogrom, p_exec 
Parameters: long, to environment string, long: pointer 

to caatjjksgA line, long: pointer to filename, word: 
mode 

Result: DO.L=(depends on mode) 

Stack: 16 

This call can be used for loading and chaining programs. The mode 
word can be one of: 


0 load and execute 

3 load but do not execute 

4 execute base page 

5 create base page 

For load and execute, the return value is either an error code, or the 
value returned when the child program exited. 
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For load but don't execute the return value Is either an error code, 
or a pointer to the base page of the loaded program. 

A discussion of using modes 4 and 5 Is beyond the scope of this 
document. 

The command line should be of the form of a length byte followed 
by the line Itself. 

The environment string may be passed as 0 to Inherit the 
programs parents basepage, or as a pointer to a list of null- 
terminated environment strings, ending In a double-null. The w 
normal environment looks like this: 

dc.b 1 PATH=',0,' A: \, 0,0 

$4C - Terminate Program, pjerm 
Parameters: word: return value 

Result: N/A as doesn't return 

Stack: N/A 

This terminates the current program, returning :«ts»fcra$ to) the 
calling program. The word value returned should bc/Bi'CTlW 
or 0 for no error. Returned error codes should be positive? to avoid 
confusion with system error codes, which are negative. 

$4E - Search for First, f_sflrst 

Parameters: word: attributes, long: pointer to fllespec 
Result: DO.W=0 If found, else -33 not found 

Stack: 8 

This trap can be used to scan a directory using wild-cards to find 
all the files. This should be called to find the first one. then f_$next 
should be called for the rest. When a file Is found the parameters of 
the file are returned In the DTA buffer area. The attribute word i 
determines which file types are to be Included In the search, and 
may be one of: 

00 normal files 
01 read only files 
02 hidden files 

04 system files 

08 return volume name only 
$10 sub-directories 

$20 files that have been written to and closed 
The values In the DTA buffer are: 
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0-20 reserved for internal use 

21 file attributes 

22-23 file time stamp 

24-25 file date stamp 

26-29 file size (long) 

30-43 name and extension of file, null terminated 

The address of the DTA buffer can be set with function $1A, and 
read with function $2F. 

< $4F - Search for Next Occurrence, f_snext 

^ Parameters: None 

Result: D0.W=0 if found, else -33 not found 

Stack: 2 

After calling f_sflrst to find the first occurrence of a fllespec, this call 
is used to tod subsequent files. When a file is found the DTA buffer 
is filled as described previously. For it to work the first 20 bytes of 
the DTA must remain untouched between calls. 

$56 - Rename a file, (.rename 

Parameters: long: pointer to new name, long: pointer to old 

name, word: 0 

Result: D0.W=0 if OK. else error code 

Stack: 12 

This will attempt to rename the file to the new name. A file with the 
new name must not already exist. 

$57 - Get/Set File Date & Time Stamp 

Parameters: word: 0 for Get / 1 for Set. word: file handle, long: 

pointer to buffer 
Result: None 

Stack: 10 

^ This can be used to get or set the time and date stamp on an open 
file. The buffer should contain two words, the first being the time, 
and the second the date, in the format already described. 
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BIOS - Basic I/O System 


The ST BIOS Is Intended for low-level access to the screen, 
keyboard and disk drives. It Is accessed using the stack for 
parameters as described previously, but using TRAP #13 to Invoke 
It. Programmers who require access to the BIOS are likely to need 
much more detail than we could provide, so only one BIOS call is 
described here. For greater BIOS detail sec the books In the 
bibliography. The BIOS handler preserves registers D3-D7/A3-A7 - 
all others may be corrupted by a call. 

BIOS 5 - Set Exception Vector, setexc 

This Is a very useful trap and sets certain system vectors to point 
to your own routines. It can set both exception vectors and system 
vectors. The calling sequence Is: 



addq.1 


Bmyroutine,-(a7) 
Bvectornum,-(a7) 
#5,-<a7> 

113 

#8,a7 

dO,oldroutine 


address of new handler 
vector number 
BIOS function number 
dolt 

restore stack 
store old one 


The vector number should be the exception number (2 for bus 
error, 3 for address error etc.), or one of the following system 
vectors: 


$45 200Hz list 

$100 system timer Interrupt 
$101 critical error handler 
$102 process terminate hook 

On return from the trap DO.L contains the previous value. If a ^ 
program modifies any vectors It should always restore them to 
their original values before terminating. 

If you pass an address of -1 It will not be changed, but the current 
value will be returned in do.l. 
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XBIOS - Extended BIOS 


The XBIOS consists of 40 functions for a wide variety of functions 
including hardware access, screen control, and keyboard mapping. 
Again we leave most of the description to the books in the 
bibliography, with the exception of five XBIOS calls. The XBIOS 
handler preserves registers D3-D7/A3-A7 - all others can be 
corrupted by a call. The calling sequence 13 the Usual one: put 
parameters on the stack, put a function w cscii or; the stack, do a 
TRAP #14. then restore the stack. The XBIOS fUKctkins are: 

XBIOS 2 - Get Physical Screen AdviM*. _physbase 
Parameters: None 
Result: D0.L=start of eeatfsn 

Stack: 2 

This will return the physical address of the screen, which always 
occupies 32000 bytes and is aligned on a 256-byte boundary. 

XBIOS 3 - Get topical Screen Address, Jogbase 

Parameters: None 

Result DO.L=start of screen 

Stack: 2 

This will return the logical address of the screen. 

XBIOS 4 - Get Screen Resolution, _getRez 

Parameters: None 

Result: D0.W=0 low. 1 medium, 2 high 

Stack: 2 

This will return the current screen resolution. 

XBIOS 5 - Set Screen Address & Mode, _setScreen 
Parameters: word: mode, long: physical address, long: logical 
address 

Result: None 

Stack: 12 

This lets you change the screen resolution and addresses. If any 
parameter is specified as -1 the it is left alone. Changing the screen 
mode will clear the screen. 

XBIOS $26 - Call Supervisor Routine, supexec 
Parameters: long: address of routine 

Result: None 

Stack: 6 

This will call the given routine in supervisor mode. The routine 
should not make any BIOS, XBIOS or GEMDOS calls. 


HISoft DevpacST The Operating System 


Page 155 


GEM Libraries 


GEM Itself consists of two components; the VDI and the AES. 

The GEM VDI (for Virtual Device Interface) Is the main part of the 
operating system that draws graphics and text on the screen. 

The GEM AES (for Application EnvlirASipif?: Services) Is the part of 
the operating system that provides ’r-lnterface facilities of 
GEM such as windows, menus and dr i b i Syxes. 

This section Is intended to give details of the supplied library files 
and calling conventions used. It does not attempt to describe either 
the VDI or the AES in great detail - the books In the Bibliography 
should be referred to for this. However, details are given of 
Information that we feel Is badly documented or not documented 
at all. 

GEM AES Library _ 

The calling sequence to the AES Is based on various arrays of 
words and longwords. These arrays are defined using DS directives 
and are; 

control words 
int_in words 
addr_in longwords 
int_out words 
addr_out words 
aes_params longwords 
global • words 

For example the C program segment 

val-int_out(2)+int_out(3) 
could be converted Into this assembly language; 

move.w int_out+4,dO 
add.w int_out+6,d0 

Note the way that the array Index is doubled before adding to the 
start of the array, as It Is an array of words. For an array of longs 
the Index should be quadrupled. 
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A macro file, called gemmacro . S should be used which defines 
various macros and. If generating executable code, the file aeslib.S 
should be Included at the end of assembly. 

The macros take a varying number of parameters and place them 
in the required places In the AES arrays, before making a call to the 
general AES routine. If passing a constant to a macro be sure to 
precede It with a # sign, for example passing the parameters 
3,tegpbK to- a snaorp could generate the code 

imowc.w 3,int_in 
nwVfii'l, myptr,addr_in 

'Tha'ftnst&oc wfit. tiause a run-tlme error, the parameter should 
bame-bnrig 3,. There are a few AES macros which do not take all the 
ra^ti^retl parameters - additional information may have to be 
plitmi to other - arrays. On return from an AES macro DO.W (and 
the fiags)' reflect, the contents of the array lnt_out(0), normally 
usiefut Various rstlim values can often be found In the lnt_out 
«mty. .. . . 

The following descriptions assume all parameters to be word sized, 
unless shown wfth a .L suffix, denoting a longword parameter. 

Application Library _ 

appljnlt 

Should be called at the start of any AES program. 

«$>»S_read Id,length,buffer. L 
tWS.write Id,length,buffer! 
appLflnd name! 

Find a named program, normally a desk accessoiy 
appljplay memory!,number,scale 
appljrecord memory!,count 
appLexit 

Should be Just before an AES program terminates. It sends 
AC_CLOSE type messages to all desk accessories. 
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Event Library 


evnt_keybd 

evnt_button clicks,mask,stale 

The return value Is the number of times the button entered the 
desired state. Array elements 1-4 of lnt_out contain the X co¬ 
ordinate. the Y co-ordinate, the button state and the keyboard 
state at the time of the event In that order. 

evnt_mouse flags, x.y.w.h 

The return values are as described for the previous call. 
evnt_mesag buffer! 
evntjimer count! 

ovnt_multl flags, clicks, mask, m I flags,m lx,mly,m lw,m Ih, 

& m2Hags,m2x,m2y,m2w,m2h,count! 

All parameters except the first are optional, specifying a null 
parameter means nothing Is placed In the relevant element of 
Intjn. It Is shown above with the syntax of a multi-line macro call 
but this Is not obligatory. The lnt_out array contains which event, 
mouse X. mouse Y. button, keyboard state, keyboard code and 
button value, respectively. 

evnt_dcllck new.getset 

Menu Library _ 


menu_bar free!,show 
menujcheck tree.L,ltem,check 
menujenable tree!,Item,enable 
menujnormal tree.L,tltle,normal 
menu_text tree.L.item.text.L 
menu.register Id,string 
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Normally a menu tree Is generated by a resource 
editor though they can be constructed, with a great deal of care, by 
hand. Another alternative Is to use the MENU2ASM compiler, 
detailed later In this section. 


Object Library 


Object trees are normally constructed with a resource editor. 
L, though they can be constructed by hand If required. Dialog boxes 
are the easiest type of object tree to construct by hand and menus 
the most difficult. 

objc.add tree. L,parent, child 
objc_delete tree.L,object 
objc_draw tree.L,startob,depth,x.y.w.h 
objc_find tree.L,startob,depth, x.y 
objc.offset tree.L,object 

Elements 1 and 2 of int_out contain the returned X and Y co¬ 
ordinates. 

objc.order tree.L,object,newpos 
objc.edit tree.L,obJect,char,Idx,kind 
int_out(l) contains the new idx. 

'w objc.chang© tree.L, object, x, y, w, h. naw,redraw 

Form Library ____ 

form_do tree.L,startob 

Never pass startob as -1 as often documented, use 0 Instead. 
form_dlal ttag,x1,yl,wl,hl,x2,y2,w2,h2 
form_alert button,string! 
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Error numbers should be positive and less than 64. 
!orm_center tree.L 

Graphics Library _ 


graf_rubberbox x,y,w,h 

lnt_out(l) contains the finish width, Int out(2) the height. , 

w* 

graf_dragbox w,h,x,y,bx,by,bw,bh 

lnt_out(l) contains the finish X co-ordinate. lnt_out(2) the Y. 

graf_movebox w,h,x,y,dx,dy 

graf_growbox x,y,w,h,(x,fy,fw,(h 

graf_shrinkbox x,y,w,h,sx,sy,sw,sh 

graf.watchbox tree.L,ob/ect,Instate,outstato 

graf.slidebox tree.L,parent,obj,vh 

graf.handle 

The lnt_out array will contain the VDI handle, character cell width, 
then height, system font width, then height. 

graf.mouse number,address! 

The address parameter Is optional, only required If defining you J 
own shape. ^ 

graf.mkstate 

The lnt_out array will contain a reserved vg'fj,,. xx-^nc X and Y 
position, mouse button state and keyboard 

Scrap Library _ 

scrp_read buffer.L 
scrp_wrife buffer:L 
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File Selector Library 


fseljnput path.L,filename! 

The path parameter should point to a buffer containing the null- 
terminated path, such as A:\*.S. and the new path will be 
returned in it. so be sure it is large enough. The filename buffer 
should be 13 bytes, with a maximum of 12 used for the filename, 
for example test.s. If DO.W is non-zero on return then it means 
there was not enough free memory to tavotce the selector, else 
Int.ouKl) will contain. 0 if Cancelled. 

Window Library ___ 

winCLc{«J{» kbKf r x,y,w,h 
wlnd..op*n 
wlncLelosw hmtila 
wlnd,„d»Sef® handle 

wlnd.get hand/e, f/e/d 
wind_sethand/e,f/e/d 
wlnd_flnd x,y 
wind.update begend 
wind_calc type,kind,lnx,lny,lnw,inh 

Resource Library __ 

rsrcjoad filename! 

mfejtee 

gaddr type,Index 

The result address may be found in addr_out. 
rsrc_saddr type,Index,saddr.L 
rsrc_obflx tree!,object 
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Shell Library 


shel_read command!,shell! 
shel_write doex,sgr.scr.cmd!,shell! 

We have never managed to get this call to work reliably, 
shel.find buffer! 

The buffer should be a minimum of 80 bytes. 
shel_envm value!,siring! 

Debugging AES Calls _ 

Unlike the calls to the VDI, calls to the AES are not Immediately 
obvious when viewed from MonST as they are of the form 


moveq »??,d0 AES function number 

bsr CALLAES 


e listing at! the AES calls 


A appljnlt 
D appljlnd 
13 appLexit 
16 evn»_mou$e 
19 evnt.mulli 
IF menu.lcheck 
22 menu.lext 
29 ob|c delete 
2C objc.oflset 
2F objc.change 
34 form.alert 
46 grat.rubberbox 
49 gral.growbox 
4C gral.slldebox 
4F graf.mkstate 
54 fseljnput 
66 wlnd.close 
<f) wlnd.set 
6C wlnd.calc 
10 rsrc.gaddr 
78 shel.read 
7B shel.envrn 


0 

5 awCtjsteiy 
svnL 

17 

1A •VM.delse* 

6 

V. xiernijegmer 
A »b}c 
2D ebJc„o«i*r 
5£ 

35 

*? ero'LdragJ?*)* 

44 g-Mfh&iKoox 
4D grdLftdndle 
£0 scrp.read 
64 wlnd.create 
67 wlnd.delete 
64 wlndjlnd 
6E rsrcjoad 
71 rsrc.saddr 
T9 shel.wrlle 


C 1 «3?ipl_wrlte 
f IJrecord 

,'tS e/ t .button 
w evtsfjlmer 
13 jnenu.bar 
21 trn*ju_lnormal 
o.bjc.add 
SB MfBjmd 
& obie.edll 
I '<i ! jifn_dlal 

Si fefS.center 
4f5 &Wt_n>ovebox 
dZ gwLwatchbox 
4c grav.mouse 
51 scrp.wrile 
66 wind.open 
<8 wlnd.get 
6B wlnd.update 
6F rsrcjree 
72 rsrc.obflx 
7A shel.flnd 
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GEM VD1 Library 


The calling sequence Itself to the VDI Is, like the AES. based on 
various arrays of words and longwords. These arrays are defined 
using DS directives and are: 

contrl words 
intin words 
ptsin words 
intout words 
ptsout words 
vdi_params longwords 

All (but one) VDI calls require a VDI handle, which by tradition Is a 
parameter to every call. However, the majority of programs only 
use one handle, to a virtual workstation (the screen), so the 
supplied VDI libraries use a word called current_handle as the 
handle to pass on to the VDI itself. This saves an appreciable 
amount of code and Is the same way the HISoft BASIC libraries 
work. As the source to the library is supplied you could change 
this, if required. 

The macro file gemmacro.S should be used which defines various 
macros and. If generating executable code, the file vdilib.S should 
be included at the end of assembly. 

The macros take a varying number of parameters and place them 
in the required places in the VDI arrays, before making a call to a 
VDI library routine. The warning about I signs in parameters 
described previously applies to the VDI too. There are a number of 
VDI macros which do not take all the required parameters - 
additional Information may have to be placed in other arrays. On 
return, various return values can often be found in the Intout and 
ptsout arrays. 

The following descriptions assume all parameters to be word sized, 
unless shown with a -L suffix, denoting a longword parameter. 
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Control Functions 


v_opnwk Open Workstation 

This should not be used unless GDOS is installed. The Intln array 
should be suitably initialised. current_handle will be set to the 
result of this call. 


v_clswk 

v_opnvwk 


Close Workstation 
Open Virtual workstation 


This uses current_handle to open another workstation and sets 
current_handle to the result, intin is normally filled with 10 words 
of 1 and one word of 2 (denoting RC co-ordinates). 


v_clsvwk 

v_clrwrk 

v_updwk 

vstjoadjonts 


Close Virtual Workstation 
Clear Workstation 
Update Workstation 
Load Fonts 


Do not attempt this unless GDOS Is loaded. 

vst_unload_fonts Unload Fonts 

Fonts must be unloaded before a workstation is closed. 

vs.cllp flag,xl,y1,x2,y2 Set Clipping Rectangle 

Output Functions _ 


v_pline count Polyline 

The input co-ordinates should fee^j^ed to Intin before the call. 
v_pmarker count Polymarker 

The input co-ordinates :$!&$$$ be copied to intin before the call. 
v_gtext x,y,string! ' > Text 

The string should be in the from of null-terminated bytes. 
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The Input co-ordinates should be copied to Intin before the call. 
v_contourfill x,y,Index Contour Fill 

vr_recfl xl,y1,x2,y2 Fill Rectangle 


v_arc x,y,radius,start,end 
v_pie$llce x,y, radius, start, end 
v_clrcle x,y,radius 

v_ellarc x,y,xradlus,yradlus,start,end 

v_ellpi e x.y.xradlus.yradlus,start,end 

v_ellipse x,y,xradlus,yradlus 

vjboxxl,yl,x2,y2 

v_rfbox xl.yh^^ 

vjustlfied x,yj&t:$JJength,ws,cs 

The string should be null-terminated. 


Arc 

Pie 

Circle 

Elliptical Arc 
Elliptical Pie 
Ellipse 

Rounded Rectangle 
Filled Rounded Rectangle 
Justified Graphics Text 


Attribute Functions 


vswr_mode mode 
vs_color Index,red,green,blue 
vsljype style 
vsl_udsty pattern 
vsl_width width 
vsl_color Index 
vsl_ends begin, end 
vsm_type symbol 


Set Writing Mode 
Set Colour Representation 
Set Polyline Une Type 
Set User Defined Line Style Pattern 
Set Polyline Une Width 
Set PetyfiSie Colour Index 
byline End Styles 
Set Polymarker Type 
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vsmjieight height 
vsm_color Index 
vst_helght height 


Set Polymarker Height 
Set Polymarker Colour Index 
Set Character Height, Absolute Mode 


The ptsout array will contain the selected size. 

vst_poln! point Set Character Height, Points Mode 

The ptsout array will contain the selected size. 


vst_rotation angle 

vstjont font 

vst_color Index 

vsLeffecfs effect 

vst_allgnment horizontal,vertical 

vsfjnterlor style 

vsf_style Index 

vsf_color Index 

vsf_perimeter vis 

vsf_updat 


Set Character Baseline Vector 
Set Text Face 
Set Graphic Text Colour Index 
Set Graphic Text Special Effects 
Set Graphic Text Alignment 
Set Fill Interior Style 
Set Fill Style Index 
Set Fill Colour Index 
Set Fill Perimeter Visibility 
Set User Defined Fill Pattern 


The intln array should be filled with the pattern and contrl(3) set 
suitably. 

Raster Operations _ 


vro.cpyfm mode,source!,dest.L Copy Raster, Opaque 

This Is the general blit call, most often used for scrolling the screen. 
The source and destination parameters should point to a memory 
form definition block (MFDB) which describes the format of the 
memory to blit. An MFDB consists of ten words: 

0 high word of address 

2 low word of address 

4 width In pixels 
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10 

12 

14-18 


height In pixels 
width in words 
form flag, normally 1 
number of planes 
reserved, set to 0 

The address In the first two words Is normally either the screen 
address or the address of a buffer being used for the blit. The width 
and height fields should be those suitable for the screen size and 
the number of planes can be found from a vq_extnd 1 call in 
; lntout(4). When scrolling the screen the source and destination 
parameters may point to the same MFDB. 

The source and destination rectangles should be placed In the plsln 
array, each In the form xl,yl.x2,y2. A mode of 3 means replace. 

vrt_cpyfm mode,source.L,dest.L,l 1,12 Copy Raster, Transparent 

vr_tmfm source.L,destination.L Transform Form 

v_get_plxel x,y Get Pixel 

Input Functions _ 


vexjimv newllmer 
v_show_c reset 
v_hide_c 
vq_mouse 
vex_butv newxbut 
vex_motv newmotv 
vex_curv newcursor 
vq_key_s 

Inquire Functions 


Exchange Timer Interrupt Vector 
Show Cursor 
Hide Cursor 
Sample Mouse Button State 
Exchange Button Change Vector 
Exchange Mouse Movement Vector 
Exchange Cursor Change Vector 
Sample Keyboard State Information 


vq_extnd flag Extended Inquire 

vq_color Index,flag Inquire Colour Representation 
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vql_attributes 
vqm_attrlbutes 
vqf_attributes 
vqt_attributes 
vqt_ex»ent string. L 


Inquire Polyline Attributes 
Inquire Polymarker Attributes 
Inquire Fill Area Attributes 
Inquire Graphic Text Attributes 
Inquire Text Extent 


The string should be null-terminated, the results will be found In 
ptsout. 

vqt.wldth char Inquire Character Cell Width 

vqt_name number Inquire Face Name & Index 

vqtjontlnfo Inquire Current Face Information 

AES & VDI Program Skeleton_ 


The general structure of a GEM-type program is as follows: 
shrink memory call 
call appljnlt 

set current_handle to the result from graf_handle 
open a virtual workstation using this handle 
open a window, perhaps 
main wait for events & act on them as required 
quit close any window 

close virtual workstation 
call appLexIt 
finally pjerm 
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Desk Acffifrs$&rles 


A desk accesSsay is an executable file with the extension . ACC 
loaded during AILS initialisation. We have never seen any official 
documentation on desk accessories, and the following Information 
has been learnt the hard way. mainly when writing our Saved! 
program. 

The first thing to be wary of Is that It Is not a normal GEMDOS 
program. When It starts up all registers Including A7 are 0. with 
*w the exception of AO which points to the basepage. An accessory 
must Include all the memory it requires within Itself, the BSS 
segment being a good place. An accessory must not do a GEMDOS 
shrink call or attempt to terminate. 

The main loop of an accessory Is like any other AES program, 
consisting of an event loop, but note that most documentation 
details incorrect message numbers - AC_OPEN is really 40 and 
AC.CLOSE is 41. 

Other programmers have reported problems using the VD1 from 
within an accessory. The recommended method Is to open a virtual 
workstation only when you have to (l.e. before creating a window) 
and always close It (when you close your window or. falling that, 
when receiving an AC_CLOSE message. The example accessory 
supplied, like our Savedl program, does not use the VDI at all • 
paranoia rules! 

If your accessory responds to timer events ensure that no 
GEMDOS calls (Trap #ls) are made unless your window Is the 
front one. otherwise time bombs will be set and a crash Is highly 

The file desk&cc. $ contains the source to an example accessoiy, 
which simply dSapSsys the system free memory in an alert box. It 
has a label called K'JNNer which can be set to 1 to produce a stand¬ 
alone application Instead of an accessoiy. This can be Invaluable 
during program development as you can symbolically debug a 
stand-alone program, while an accessory has to be debugged using 
amonst without the benefit of symbols. 
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Linking with AES & VDI Llbra ?'^ _ __ 

The supplied macro file gemmacro . $-!» to be used In 

executable or linkable programs. The fifes assisis. S and vdilib . s 
contain the actual code and shouts be ta«sWtJ©3 at the end of 
programs when generating executssbi® codJe, if generating 
linkable code they should not. If you 9^ . s you can see 

how a conditional is used to make this automatic. 

When developing a program using these libraries we recommend 
executable code as it greatly reduces development time. However 
the file size can be reduced by using the selective library feature of 
the linker and using the Gemlib.bin file. For example. If gemtest is 
linked to GST-linkable code, producing gemtest.bin, it can be 
linked with this library by passing LinkST the command line 

gemCesC -wgemlib 

The gemlib.lnk control file will do the rest. If you want to reduce 
your program to the absolute minimum then you can change the 
libraries as you require, which Is why we supply the source code. 

Menu Compiler _ 


For those who wish to use menus without using a resource editor 
we supply the program menu2asm.ttp which converts a menu 
definition file into assembly language source statement for 
Inclusion in your program. We use this method ourselves in the 
GenST editor. 

The menu speclllcatlon should be created in a text file with the 
extension .mdf and an example follows: 

( Desk I About Program ] 

( File I New \ Load \<-\ Quit 1 

( Search I Find ) 

and so on. Line breaks are ignored. Each menu title and its items 
are enclosed in square brackets ( and ). There is a vertical bar (|) 
after each title and the individual items separated by back-slashes 
(\). For grey items precede the text with an open parentheses (. 
The first menu is always the desk title (normally Desk): the 
currently loaded desk accessories will be added by the AES. (It is no 
coincidence that this is the same syntax as that accepted by our 
BASIC compilers). 
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We recommend that you precede each menu Item with two spaces 
and have at least one space after the Item. Menu titles should have 
one space before and after them. 

To compile a file double-click on MENU2ASM.TTP and enter the 
filename, without an extension. It will produce a file with an 
extension of .mnu which may be Included In your program. 

The file menutest.mdf contains an example definition of a menu 
and menutest . s the source code to a program Illustrating Its use. 
as well as showing other AES features. 

Old GenST AES & VDI Libraries_ 


The folder oldgen contains updated versions of the source files 
supplied with version 1 of DevpacST. These use different calling 
conventions and are supplied for users who have upgraded. 
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VT52 Screen Codes 


When writing to the screen via the BDOS or 8K2-S calls, the screen 
driver emulates VT52 protocols. The control codes are sent via 
escape sequences, which means an escape character is sent (27 
decimal, or $1B) followed by one or more other characters. 

ESC A cursor up; no effect If at the top line 

ESC B cursor down; no effect if at the bottom line 

esc C cursor right; no effect if on the right hand side 

esc d cursor left; no effect if on left hand side 

ESC E clear screen and home cursor 

ESC H home cursor 

esc i move cursor up one line; if at top scrolls the screen down 

a line 

esc J erase to end of screen, from the cursor position onwards 
esk K clear to end of line 

esc L insert a line by moving all following lines down. Cursor Is 
positioned at start of the new line 
ESC m delete a line by moving all following lines up 
ESC Y position cursor; should be followed by two characters, 
the first being the Y position, the second the X. Row and 
column numbering starts at (32. 32) which Is the top left 
esc b foreground colour; should be followed by a character to 
determine the colour, of which the four lowest bits arc 
used 

esc c background colour; similar to above 

ESC d erase from beginning of display to the cursor position 

esc e enable cursor 

esc f disable cursor 

esc j save the current cursor position 

esc k restore a cursor position saved using esc j 

esc 1 erase a line and put cursor at start of line 

ESC o erase from start of line to cursor position 

esc p inverse video on 

esc q inverse video off 

ESC v wrap around at end of line on 

ESC w wrap around at end of line off 
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Appendix E 
Converting from other 
Assemblers 


Most 68000 assemblers for the ST follow, to one degree or another, 
the Motorola standard. While the Instructions themselves arc 
thankfully standard, the syntax rules for laJw,!?, comments and 
directives can. and do. vary. This Appendix ©Mere the changes 
most likely to be made when converting psxgsmas from another 
assembler, whether they are your old sovtse Sites or a program 
listed In a magazine. It does not attempt to detail the differences In 
user Interfaces or options between the different assemblers. 

Atari MADMAC_ 


GenST does not require colons after labels or comments to be 
delimited with semi-colons, but It does not allow instructions or 
directives to start In the label field. 

The syntax and rules for local labels are the same, though S and ? 
are not valid In GenST symbols. The use of \ In quoted strings may 
have to be changed, and some arithmetic operators and priorities 
are different. 

MADMAC allows directives to start with dot. If these are removed 
most directives are the same as GenST. Those that differ, and their 
GenST equivalents, are: 

BSS=SECTION BSS. DATA=SECTION DATA. TEXT=SECTION TEXT. 
ABS=OFFSET, ELSE=ELSEIF. ENDIF=ENDC. EXITM=MEXIT. GLOBL and 
EXTERN=XREF or XDEF. EJECT=PAGE. TITIE=TTL. NUST=NOLIST. 

INIT can be converted to DC or DCB statements and CARGS can be 
replaced with suitable RS directives. 

MADMACs macro syntax Is unique and Its named parameters will 
need conversion, equivalents for Its parameters are \~=\@ and 
\#=NARG, \? can be emulated using IFC or IFNC. The 6502 options 
of MADMAC are not supported. 
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GST-ASM 


GST labels are significant only to the first 8 characters and are 
case insensitive so OPT C8- may be required. Its rules for 
expression evaluation are very similar though $ is not allowed 
within a GenST symbol. 

Most directives are the same, those requiring name changes are 
PAGEWID=LLEN and PAGELEN=PLEN. Macro definitions will require 
conversion as will GSTs unique form of local symbols. 

Built-in functions and structure statements are not supported. 

MCC Assembler_ 


Veiy few changes are required, only the syntax for local labels and 
add 1 to XREF directives of absolutes. 

K-Seka 


Colons are not required after labels in GenST though Instructions 
or directives that start in the label field will need a tab added before 
them. Several Seka directives default to Byte Instead of Word sizes 
for some reason. Equivalent directives names are: 

D=DC, BLK=DS, CODE=SECTION CODE. DATA=SECTION DATA,, 
IF=IFNE, ELSE=ELSEIF. ENDIF=ENDC. 

Macro syntax requires ?s to be changed to \s, except ?0 which 
should be replaced with \@. 

Fast ASM 


The syntax of Fast ASM was designed around GenST 1.2 so few 
changes are rsqulxed, Tokenlsed source files will need conversion 
to ASCII fusing the Clipboard) before attempting to load tbens tota 
the GenST editor. 'ftie main change involves comment deliiffidters - 
Fast ASM teas starting with \ should be changed to start with * or 
: - \s used alte Detractions will not require any change. 

The flo&lliig peSni facilities in Fast ASM. left over from its BASIC 
interpreter origins, are not supported in GenST. 
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Appendix F 
Bibliography 


This bibliography contains our suggestions for further reading on 
the subject of the 68000. the ST. and GEM. The views expressed are 
our own and as with all reference books there is no substitute for 
looking at the books in a good bookshop before making a decision. 

68000 Programming _ 

M68000 Programmer's Reference Manual 
_ Published by Prentice-Hall _ 

The definitive guide to the Instruction set produce by Motorola. The 
supplied Pocket Guide is a subset of this book. Be sure to get the 
latest version - at the time of writing the Fifth Edition Is the latest. 

68000 Assembly Language Programming by Kane, Hawkins 8i 
_ Leventhal, published by Osbome/McGraw-HIII _ 

This Is large (and expensive) but good, containing lots of examples. 
Be sure to get the second edition. Not for complete beginners to 
microprocessors. 

68000 Tricks and Traps by Mike Morton 

_ BYTE magazine, September 1966 Issue _ 

By far the best article on 68000 programming we have ever seen. 
We wish there was a book like this. 

ST Technical Manuals_ 


GEM Programmer's Guide Volumes 1 & 2 - VDI and AES 
_ by Digital Research 

The definitive guide to the VDI and AES. but marred by mistakes 
and lack of 68000 details. Only available to registered developers. 
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GEMDOS Specification by Digital Research 


The definition of the GEMDOS calls. Only available to registered 
developers. 

A Hitchhikers Guide to the BIOS by Atari Corp _ 

The definition of the BIOS and XBIOS calls, and corrections to the 
GEMDOS manual. This Is accurate, a good read and updated 
regularly. Normally only available to developers. 

The Anatomy of the Atari ST by Data Becker/Abacus _ 

This book Is the best documentation available for the user who Is 
not a registered developer. It describes the hardware and non- 
GEM aspects of the operating system, including an (out-of-date) 
BIOS listing. Thoroughly recommended, despite its Inaccuracies. 

GEM on tho Atari ST by Data Becker/Abacus _ 


This describes programming under GEM. though is not as 
complete as the DR manual, but has similar errors. It describe* 
calls mainly from C. although there is more reference to the SSflOO 
than in the DR manual. Better than no book at all on GEM. 

Concise Atari 68000 Programmer's Reference 
_ by Katherine Peel, published by Glentop _ 

An alternative to Atari ST Internals. It contains information on the 
STs hardware, the operating system and GEM. Its coverage of the 
various levels of the machine Is comprehensive, though a couple of 
sections are very inaccurate and some features are described that w 1 
simply don't exist. It is rather difficult to find one's way around as 
the layout is based on large numbers of tables and it lacks an index. 

Tricks and Tips on the Atari ST by Data Becker/Abacus _ 

This contains a wide variety of material. Including an accurate 
description of the more esoteric ST BASIC commands, and good 
sample; listings including a RAM-dlsk driver and desk accessory. 
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M68000 Cross Macro Assembler Reference Manual 
_ Published by Motorola (M68KXASM ) _ 

The official definition of 68000 assembly-language syntax on 
which GenST is based. 

M68000 Resident Structured Assembler Reference Manual 
_ Published by Motorola (M68KMASM ) _ 

This details the more advance aspects of the Motorola standard 
Including extended macros and 68010/20/881 processors. 
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Appendix G 
Technical Support 
& Upgrades 


So that we can maintain the quality of our technical support 
l , service we are detailing how to take best advantage of It. These 
guidelines will make It easier for us to help you, fix bugs as they get 
reported and save other users from having the same problem. 
Technical support Is available In three ways: 

• Phone our technical support hour Is normally between 3pm and 

4pm, though non-European customers' calls will be 
accepted at other times. 

• Post If sending a disk, please put your name & address on It. 

• BUT™ our username Is (not surprisingly) hisoft. Would UK 

customers please use more old fashioned methods; It's 
cheaper for everyone. 

Whichever method you use please always quote your serial 
number (from your master disk) and the version number of the 
program. We reserve the right to refuse technical support If you do 
not supply this Information. 

For bug reports, please run the CHECKS?'.PRG program supplied and 
quote the Information given by It, as weli as details of any desk 
'w accessories and auto-folder programs in Use. If you think you have 
found a bug, try and create a small program that reproduces the 
problem. It Is always easier for us to answer your questions If you 
send us a letter and. If the problem Is with a particular source file, 
enclose a copy on disk (which we will return). 
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Upgrades 


As with all our products. DevpacST Is undergoing continual 
development and. periodically, new versions become available. We 
make a small charge for upgrades, though If extensive additional 
documentation Is supplied the charge may be higher. All users who 
return their registration cards will be notllled of major upgrades. 

Suggestions _ 

We welcome any comments or suggestions about our programs; 
and, to ensure we remember them, they should be made ln wriitef*. 

DevpacST Dgvgtoger Version _ 

For those that require maximum power from their 68000 
assembler we have available the Developer version of DevpacST. 
Features over and above this version Include: 

GDOS Is supplied together with documentation, sample program 
and calling sequences; Motorola 8 record hex output and multlple- 
ORG statements for users cross-developing; Amiga executable & 
linkable file formats; 68010/20/30/881/882 Instructions; Dual 
machine debugging: Detailed notes on GST & DRI file formats 
Including special dump programs for both formats, source (In 
HISoft BASIC) included; Free upgrades for a year, despatched 
automatically. 

DevpacST Developer Is available as an upgrade. 
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Appendix H 
Revision history 

Product History_ 


DevpacST 0.50 was first released In late 1985. but with various 
restrictions to do with the editor and the lack of linkable code. The 
OSXt major version was 0.91 which was much Improved In many 
suspects, followed by 0.99f. the last version which didn't produce 
&KKable code. Version 1.0 was released In April 1986, and 
underwent a few minor changes before the release of version 1.22 
In June 1986. the first version supplied In a ring-bound manual. 
After various small revisions the greatly Improved version 2.0 was 
released In April 1988. 

Development Technique _ 

DevpacST was originally based on DevpacQL, our Assembler 
Development suite Tor the Sinclair QL. Both GenST and MonST 
were written In assembler on the QL then uploaded via the serial 
port Into the ST. and LinkST was written using Lattice C on the ST. 
Development moved across to the ST around version 1.24 which 
had minor changes made, reaching version 1.26. Special Internal 
versions were written to experiment with things like linkable code 
and extended debug and reached version 1.57 before both GenST 
and MonST were completely re-written for version 2. The editor 
was extensively altered, originally for HiSoft BASIC, then Power 
BASIC, then GenST. The editor Is written entirely In assembly 
language. 

Summary of Version 2 Improvements 


This section is Intended as a quick guide to the main additional 
features for users who have upgraded from version 1.2 of 
DevpacST. It gives an overview of the new features, for further 
details you should consult the relevant sections of the new manual. 
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The Editor 


This has been greatly enhanced, with an overall improvement In 
display speed being the most obvious. The editor supports lines up 
to 240 characters in length, sideways scrolling as required. It also 
works In low-resolution. There Is now a horizontal scroll bar and 
the workings of the vertical scroll bar Is now more “standard". By 
default the numeric pad Is configured as an IBM-stylc cursor 
cluster and the text editor workspace size can now be changed 
from within the editor. This, combined with the saving of s 
preferences, means the Installation program In version 1 is W 
redundant. Other programs can be run from within the editor 
using the Run Other facility. 

Block Delete has changed to Shift-F5 from Shift-F3 (as fast left- 
handed typists can generate the shift-F3 scan-code In ordinary 
typing) and now remembers the block. If possible, allowing it to be 

B asted. A deleted line may be recalled as many times as required. A 
lock may be copied to the block buffer, and marked blocks arc now 
show on screen. Our Saved! desk accessory may be Invoked at the 
press of a key, there is a keyboard shortcut for Save, and the 
editor will now run In low-resolution. 

The Assembler 


Symbols are now significant to the first 127 characters and local 
labels are supported. The INCBIN directive takes a straight binary 
file and copies it Into the output file, particularly useful for screen 
data. Speed - Include flies are read only once, memory permitting, 
and the binary file Is buffered for as long as possible. The absolute 
maximum speed has over doubled to 75.000 lines per minute ' , 
though for real programs 35,000 lines Is the norm. The output file 
Is also extensively buffered If possible producing spectacular 
Improvements during floppy-to-floppy assemblies In particular. 

General Improvements In symbol table searching and hashing 
have also Increased overall speed. Extended Debug - a HiSoft 
extended version of the DR symbol table, allowing debugging with 
up to 22 character significance. Macro calls and Includes may be 
nested as deeply as memory allows. IFs can be 64k levels deep. 

TEJCT, DATA & BSS segments are properly supported when 
generating executable code. 
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There Is much greater eesi&Ol e?sr output IMsnames. Multiple 
Modules & Sections - She OS? Sinter \armsZ Is more fully 
supported allowing saultipl® mCKhxles and SH&tlple secUons. 
Externals may be used In expgcsssteos, with, mcii other If required. 
DRI linkable code can now be generated. 

Optimising can now be perforate*! by the aBsexsbie? on things such 
as short branches. Macros nrv? a&ppegt up te 36 parameters 
multl-Une calls and numeric substitution. The macro buffer Is now 
dynamic, the free space In the editor workspace Is no longer used 
, for this. REPEAT loops are now allowed and the expression 
evaluator now Includes comparisons. The REG directive allows 
symbolic register lists. There are a considerable number of 
extensions to the OPT dlrecUve. Octal numbers are supported. 
Registers may also be called RO through R15. A stand-alone 
assembler is supplied for those who use alternate editors, CLIs or 
batch flies. 

Compatibility Issues ___ 

Most source flies should assemble with little or no changes. The 
differences to be careful of are: BSS secUons - neither RSBSS or 
DSBSS are supported, the code should be converted to switch to 
SECTION BSS then use DS statements. Symbols now default to case- 
dependent and are significant to the first 127 characters. OPT N 
for narrow listings has been superseded with the FORMAT directive 
allowing much greater flexibility and general listing control has 
been Improved. The ORG statement has changed which will effect 
any programs that use It. 

HISoft BASIC users - If creating libraries please note that GenST 2 
output Is not accepted by BUILDLIBs prior to version 1.4. 

BRA.W wasn't accepted by version 1. forcing the use of BRA.L - this 
Is. strictly speaking, a 68020 Instruction so now generates a 
warning. BRA.W (and BRA.B) are now accepted. Various minor 
changes have been made to the parsing of Instructions allowing a 
greater degree of flexibility. If you used (expresslon)\W (denoting 
short-word addressing) within a macro this will be be Ignored as 
\W and \L refer to macro parameters and will probably be replaced 
with nulls. Use Instead (expresslon).W, which Is the Motorola 
standard. 
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The use of \W or \L after register equates used as index registers is 
no longer required, ter example if buf is a register equate then 
raove.b do,0 (a6,buf i£Bqw allowed. Register equates are now 
allowed in MOVEMs. The jKlority of the equality operator (=) has 
been changed. 

The GEM example program has been changed to use a true BSS 
section and to fix a bug preventing correct operation under GDOS - 
this and its Include flic can be found in the oldgem folder. Many 
new example Hies are supplied including a desk accessory and 
completely new AES and VDI libraries. 

The assembler now reports syntactic errors on pass 1 and will not 
start pass 2 if errors have been found. It now uses GEMDOS 
character output routines so can be paused with ctrl-s. resumed 
with Ctrl-Q and aborted with ctrl-c. 

There are several new directives which could potentially clash with 
macro names in GenST 1 source files. These are: COMMENT. DCS. 
ELSEIF. ENDR. FORMAT. HF. INCBIN. OFFSET. OUTPUT. REG. REPT, 
RSSET, SUBTTL. 

There are three reserved symbols which could theoretically clash 
with your own. all starting with two underlines: _LK, _RS and 


Debugger _ 

MonST supports a great number of new features including 
multiple windows and. as a result, has a changed user interface. It 
Is strongly recommended that you read the Reference section of 
the Chapter 4 before trying any serious work with the new version. , 
The main new features are: Multi-window display; Timed screen v** 
switching removing flicker; Full expression evaluator Including 
indirection; Supports up to 22 significant characters in symbols; 
Multi-resolution allows you to debug a low-res program in medium 
res (or vice versa); Allows the viewing of source files within the 
debugger; Disassemble to printer with automatic label generation 
or to a disk file In GenST format; Conditional breakpoints: History 
Buffer; Interrupt running programs. 

Both GEM and TOS versions of the debugger are now the same 
except for the file extension and only one auto-resident version 
needs to be supplied. 
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Integration _ 

Probably the greatest improvement to the package as a whole Is 
the Integration between Its various parts. The assembler is 
available at the press of a key from the editor, as It was. but so Is 
the debugger. The assembler can assemble directly into memory, 
then the code can be run from the editor without any disk 
accesses. If required debugging Information can also be Included In 
assembled-to-memory programs so they can be debugged at the 
press of a key. directly from the editor. A program assembled to 
memory Is a true GEMDOS task so no code changes are required. 

Assembly warnings and errors are remembered by the editor and 
can be stepped through by pressing Alt-J. Errors are no longer 
lost when the number of lines is changed, though they are not re¬ 
calculated. After an assembly which had an error the editor will 
automatically place the cursor on the line of the first error. 

Linker_ 


This now supports the HiSoft Extended Debug format and Is faster 
than Its predecessors. It also allows explicit section ordering and 
true BSS sections. Note that LinkST only supports the GST format 
- If you wish to link DRI format code you need to use the Atari aln 
or the Digital Research LINK68 linkers. 
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